[Client] Implement setMaxRetries connection retries

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}

docs/client.md

@@ -57,10 +57,32 @@ $client = Client::builder()
  ->setClientInfo('My Application', '1.0.0', 'Description of my client')
  ->setInitTimeout(30) // Seconds to wait for initialization
  ->setRequestTimeout(120) // Seconds to wait for request responses
- ->setMaxRetries(3) // Retry attempts for failed connections
+ ->setMaxRetries(3) // Retries for failed connections
  ->build();
 ```
 
+### Connection Retries
+
+`setMaxRetries()` controls how often `connect()` retries a failed connection. It
+counts retries rather than attempts, so the default of `3` means one initial
+attempt plus up to three retries — four in total — before the `ConnectionException`
+of the last attempt is rethrown:
+
+```php
+$client = Client::builder()
+ ->setMaxRetries(0) // Fail on the first failed attempt
+ ->build();
+```
+
+Between two attempts the transport is closed, so a retry never reuses a
+half-established connection: a `StdioTransport` spawns a fresh server process and
+an `HttpTransport` discards the session ID of the failed attempt. Each retry is
+preceded by a short, linearly growing delay (100ms, 200ms, 300ms, …).
+
+Only the connection handshake is retried. Individual requests such as
+`callTool()` are always sent once — retrying them is unsafe as tool calls are not
+necessarily idempotent.
+
 ### Client Information
 
 Set the client's identity reported to servers during initialization:

src/Client.php

@@ -58,6 +58,8 @@
  */
 class Client
 {
+ private const RETRY_BASE_DELAY_MS = 100;
+
  private ?TransportInterface $transport = null;
 
  public function __construct(
@@ -78,16 +80,44 @@ public static function builder(): Builder
  /**
  * Connect to an MCP server using the provided transport.
  *
- * @throws ConnectionException If connection or initialization fails
+ * A failed attempt is closed and retried, see {@see Builder::setMaxRetries()}.
+ *
+ * @throws ConnectionException If connection or initialization fails on every attempt
  */
  public function connect(TransportInterface $transport): void
  {
  $this->transport = $transport;
  $this->protocol->connect($transport, $this->config);
 
- $transport->connect();
+ $maxAttempts = $this->config->maxRetries + 1;
+
+ for ($attempt = 1; $attempt <= $maxAttempts; ++$attempt) {
+ try {
+ $transport->connect();
+
+ $this->logger->info('Client connected and initialized', ['attempt' => $attempt]);
+
+ return;
+ } catch (ConnectionException $e) {
+ // initialize() flags the session before sending the initialized
+ // notification, so a failure in between leaves the flag set.
+ $this->protocol->getState()->setInitialized(false);
 
- $this->logger->info('Client connected and initialized');
+ $transport->close();
+
+ if ($attempt === $maxAttempts) {
+ throw $e;
+ }
+
+ $this->logger->warning('Connection attempt failed, retrying', [
+ 'attempt' => $attempt,
+ 'max_attempts' => $maxAttempts,
+ 'exception' => $e,
+ ]);
+
+ usleep($attempt * self::RETRY_BASE_DELAY_MS * 1000);
+ }
+ }
  }
 
  /**

src/Client/Builder.php

@@ -96,7 +96,11 @@ public function setRequestTimeout(int $seconds): self
  }
 
  /**
- * Set maximum retry attempts for failed connections.
+ * Set the number of times a failed connection attempt is retried.
+ *
+ * Counts retries, not attempts: 3 means one initial attempt plus up to three
+ * retries. Pass 0 to fail on the first failure. Only applies to
+ * {@see Client::connect()}; individual requests are never retried.
  */
  public function setMaxRetries(int $retries): self
  {

src/Client/Configuration.php

@@ -38,5 +38,9 @@ public function __construct(
  if ($requestTimeout < 1) {
  throw new InvalidArgumentException(\sprintf('The request timeout must be a positive number of seconds, got %d.', $requestTimeout));
  }
+
+ if ($maxRetries < 0) {
+ throw new InvalidArgumentException(\sprintf('The maximum number of retries must be zero or greater, got %d.', $maxRetries));
+ }
  }
 }

src/Client/Protocol.php

@@ -179,22 +179,29 @@ public function request(Request $request, int $timeout, bool $withProgress = fal
  }
 
  $this->state->addPendingRequest($requestId, $timeout);
- $this->sendRequest($request);
 
- $immediate = $this->state->consumeResponse($requestId);
- if (null !== $immediate) {
- $this->logger->debug('Received immediate response', ['id' => $requestId]);
+ try {
+ $this->sendRequest($request);
 
- return $immediate;
- }
+ $immediate = $this->state->consumeResponse($requestId);
+ if (null !== $immediate) {
+ $this->logger->debug('Received immediate response', ['id' => $requestId]);
 
- $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+ return $immediate;
+ }
 
- return \Fiber::suspend([
- 'type' => 'await_response',
- 'request_id' => $requestId,
- 'timeout' => $timeout,
- ]);
+ $this->logger->debug('Suspending fiber for response', ['id' => $requestId]);
+
+ return \Fiber::suspend([
+ 'type' => 'await_response',
+ 'request_id' => $requestId,
+ 'timeout' => $timeout,
+ ]);
+ } finally {
+ // Only the response path clears it, so a request that timed out or
+ // whose send() threw would stay pending and fail every later one.
+ $this->state->removePendingRequest($requestId);
+ }
  }
 
  /**

tests/Integration/Fixture/request_timeout.php

@@ -0,0 +1,42 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RequestTimeoutTest}.
+ *
+ * `slow` outlives the client's request timeout and then goes idle again, which
+ * is what lets the test call `fast` on a connection the client has already
+ * given up on once.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static function (): string {
+ sleep(2);
+
+ return 'late';
+ },
+ name: 'slow',
+ description: 'Answers well after the client stopped waiting.',
+ )
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/Fixture/retry.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+/*
+ * Server for {@see \Mcp\Tests\Integration\RetryTest}.
+ *
+ * Dies before speaking a frame while the spawn counter is below the configured
+ * number of failures, so the counter file records how many processes the client
+ * actually started.
+ */
+
+use Mcp\Server;
+use Mcp\Server\Transport\StdioTransport;
+
+require_once dirname(__DIR__, 3).'/vendor/autoload.php';
+
+$counter = getenv('MCP_SPAWN_COUNTER');
+
+if (!is_string($counter) || '' === $counter) {
+ exit(1);
+}
+
+$spawns = 1 + (int) file_get_contents($counter);
+file_put_contents($counter, (string) $spawns);
+
+if ($spawns <= (int) getenv('MCP_FAIL_SPAWNS')) {
+ exit(1);
+}
+
+Server::builder()
+ ->setServerInfo('integration-server', '1.0.0')
+ ->addTool(
+ static fn (): string => 'quick',
+ name: 'fast',
+ description: 'Returns at once.',
+ )
+ ->build()
+ ->run(new StdioTransport());

tests/Integration/IntegrationTestCase.php

@@ -55,26 +55,42 @@ protected function clientBuilder(): ClientBuilder
  */
  protected function connect(string $fixture, ?ClientBuilder $client = null, array $env = []): Client
  {
- $script = __DIR__.'/Fixture/'.$fixture.'.php';
-
  $this->client = ($client ?? $this->clientBuilder())->build();
 
  try {
- $this->client->connect(new StdioTransport(
- command: \PHP_BINARY,
- args: [$script],
- // proc_open() replaces the environment rather than adding to it.
- env: [] === $env ? null : array_merge(getenv(), $env),
- ));
+ $this->client->connect($this->transport($fixture, $env));
  } catch (ConnectionException $e) {
  // The transport discards the child's stderr, so a fixture dying on
  // startup arrives here as a bare timeout.
- $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, $script));
+ $this->fail(\sprintf('Could not connect to fixture server "%s": %s. Run `%s %s` to see why.', $fixture, $e->getMessage(), \PHP_BINARY, self::script($fixture)));
  }
 
  return $this->client;
  }
 
+ /**
+ * A transport that will spawn a fixture server, without connecting it.
+ *
+ * Tests that assert on a failing connection need the transport by itself,
+ * since {@see self::connect()} turns that failure into a test failure.
+ *
+ * @param array<string, string> $env added to the server process environment
+ */
+ protected function transport(string $fixture, array $env = []): StdioTransport
+ {
+ return new StdioTransport(
+ command: \PHP_BINARY,
+ args: [self::script($fixture)],
+ // proc_open() replaces the environment rather than adding to it.
+ env: [] === $env ? null : array_merge(getenv(), $env),
+ );
+ }
+
+ private static function script(string $fixture): string
+ {
+ return __DIR__.'/Fixture/'.$fixture.'.php';
+ }
+
  protected function tearDown(): void
  {
  $this->client?->disconnect();

tests/Integration/RequestTimeoutTest.php

@@ -0,0 +1,43 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Integration;
+
+use Mcp\Exception\RequestException;
+use PHPUnit\Framework\Attributes\TestDox;
+
+/**
+ * What a timed-out request leaves behind on the connection.
+ *
+ * @see Fixture/request_timeout.php for the server under test
+ */
+final class RequestTimeoutTest extends IntegrationTestCase
+{
+ #[TestDox('an abandoned response is not handed to the next request')]
+ public function testTimedOutRequestDoesNotLeakIntoTheNext(): void
+ {
+ $client = $this->connect('request_timeout', $this->clientBuilder()->setRequestTimeout(1));
+
+ try {
+ $client->callTool('slow');
+ $this->fail('The slow tool should have outlived the request timeout.');
+ } catch (RequestException) {
+ }
+
+ // The server is still executing the abandoned call and cannot answer
+ // anything until it returns, so the next request has to wait it out.
+ sleep(2);
+
+ // Without the pending request being cleared this answers 'late': the
+ // response the client gave up on, handed to the request after it.
+ $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+ }
+}