@@ -41,6 +41,8 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * [BC Break] Fix concurrent Streamable HTTP streams on one session resuming each other's fibers: each stream now polls only the client request its own fiber sent, so an elicitation answer reaches the tool call that asked for it. `Protocol::handleFiberYield()` returns the ID of the request it sent.
 * Fix lost responses on concurrent requests of one session over Streamable HTTP: a POST is answered with its own responses instead of taking them from the session's outgoing queue.
 * [BC Break] `TransportInterface::send()` receives every response of a handler that does not suspend, not only errors raised before a session exists; the session's outgoing queue only carries server-initiated requests and notifications. A custom transport must deliver each message it gets, as a batch gets several.
+* Fix the client request timeout firing up to a second early and throwing a generic `RequestException`: it now throws `TimeoutException`, which extends `RequestException`, and sends `notifications/cancelled` for the abandoned request.
+* [BC Break] `TimeoutException` extends `RequestException` instead of `Exception`, so a `catch (RequestException)` now also catches timeouts. `ClientStateInterface::getPendingRequests()` reports `timestamp` as a `float` from `microtime(true)` instead of an `int`.
 * Serve both protocol eras over stdio: `StdioTransport` settles the era on the client's first request and serves `2026-07-28` requests, `subscriptions/listen` and `notifications/cancelled` on the one channel.
 * [BC Break] `StatelessAwareTransportInterface` declares `setHandshakeVersions()`, so a server without the modern era names only the revisions it negotiates when refusing a `2026-07-28` request, e.g. the one set with `Builder::setProtocolVersion()`.
 * Answer a bare `initialize` on a `2026-07-28`-only endpoint with `-32022` naming the served revisions, and a request without a session on the handshake leg with its id.
 
@@ -40,6 +40,24 @@ try {
 }
 ```
 
+## TimeoutException
+
+Thrown when the server does not answer within the request timeout. It extends
+`RequestException`, so catch it first to tell a timeout from an error response:
+
+```php
+use Mcp\Exception\RequestException;
+use Mcp\Exception\TimeoutException;
+
+try {
+    $result = $client->callTool('slow_tool', []);
+} catch (TimeoutException $e) {
+    echo "The server did not answer in time\n";
+} catch (RequestException $e) {
+    echo "Request failed: {$e->getMessage()}\n";
+}
+```
+
 ## Complete Example
 
 Here's a comprehensive example demonstrating client usage:
 
@@ -126,8 +126,9 @@ $transport = new HttpTransport('http://localhost:8000', listen: true);
 `timeoutSeconds: ?float` arguments. The token's `isCancellationRequested()`
 method must return without blocking. The timeout must be finite and positive
 and replaces the default request timeout for this call.
-An observed cancellation throws `RequestCancelledException`. An observed
-per-call deadline expiry throws `TimeoutException`.
+An observed cancellation throws `RequestCancelledException`. When the per-call
+or default request timeout runs out, the client throws `TimeoutException`, a
+`RequestException`, and sends `notifications/cancelled` for the request.
 
 Interruption is checked before a request goes out and again once the send
 returns. The second check is what covers a synchronous `application/json`
 
@@ -226,7 +226,7 @@ public function listTools(?string $cursor = null): ListToolsResult
      * @param float|null                                                              $timeoutSeconds Finite positive timeout replacing the default for this call
      *
      * @throws RequestCancelledException                                                      When cancellation is observed
-     * @throws Exception\TimeoutException                                                     When the per-call deadline is observed to have expired
+     * @throws Exception\TimeoutException                                                     When the request timeout is observed to have expired
      * @throws RequestException|ConnectionException|InvalidArgumentException|RuntimeException
      */
     public function callTool(string $name, array $arguments = [], ?callable $onProgress = null, ?CancellationTokenInterface $cancellation = null, ?float $timeoutSeconds = null): CallToolResult
@@ -407,7 +407,7 @@ private function sendRequest(Request $request, ?callable $onProgress = null, ?Ca
         }
 
         $withProgress = null !== $onProgress;
-        $fiber = new \Fiber(fn () => $this->protocol->request($request, $this->config->requestTimeout, $withProgress, $cancellation, $timeoutSeconds));
+        $fiber = new \Fiber(fn () => $this->protocol->request($request, $this->config->requestTimeout, $withProgress, $cancellation, $timeoutSeconds ?? $this->config->requestTimeout));
         $this->protocol->setProgressCallback($onProgress);
 
         try {
 
@@ -35,7 +35,7 @@ class ClientState implements ClientStateInterface
     private ?string $instructions = null;
     private ?ServerCapabilities $serverCapabilities = null;
 
-    /** @var array<int|string, array{request_id: int|string, timestamp: int, timeout: int}> */
+    /** @var array<int|string, array{request_id: int|string, timestamp: float, timeout: int}> */
     private array $pendingRequests = [];
 
     /** @var array<int|string, array<string, mixed>> */
@@ -53,7 +53,7 @@ public function addPendingRequest(int|string $requestId, int $timeout): void
     {
         $this->pendingRequests[$requestId] = [
             'request_id' => $requestId,
-            'timestamp' => time(),
+            'timestamp' => microtime(true),
             'timeout' => $timeout,
         ];
     }
 
@@ -49,7 +49,7 @@ public function removePendingRequest(int|string $requestId): void;
     /**
      * Get all pending requests.
      *
-     * @return array<int|string, array{request_id: int|string, timestamp: int, timeout: int}>
+     * @return array<int|string, array{request_id: int|string, timestamp: float, timeout: int}>
      */
     public function getPendingRequests(): array;
 
 
@@ -985,7 +985,7 @@ private function processFiber(): void
             }
 
             // The explicit per-call deadline replaces the default request timeout.
-            if (null === ($this->activeSuspend['deadline'] ?? null) && time() - $timestamp >= $timeout) {
+            if (null === ($this->activeSuspend['deadline'] ?? null) && microtime(true) - $timestamp >= $timeout) {
                 $this->logger->warning('Request timed out', ['request_id' => $requestId]);
                 $error = Error::forInternalError('Request timed out', $requestId);
                 $this->activeSuspend = $this->activeFiber->resume($error);
 
@@ -363,7 +363,7 @@ private function processFiber(): void
             }
 
             // Check timeout
-            if (time() - $timestamp >= $timeout) {
+            if (microtime(true) - $timestamp >= $timeout) {
                 $this->logger->warning('Request timed out', ['request_id' => $requestId]);
                 $error = Error::forInternalError('Request timed out', $requestId);
                 $this->activeSuspend = $this->activeFiber->resume($error);
 
@@ -16,6 +16,6 @@
  *
  * @author Kyrian Obikwelu <koshnawaza@gmail.com>
  */
-class TimeoutException extends Exception
+class TimeoutException extends RequestException
 {
 }
@@ -73,6 +73,29 @@ public function testDeadline(): void
         }
     }
 
+    #[TestDox('the default request timeout throws a TimeoutException, no earlier than set, and cancels the request')]
+    public function testDefaultRequestTimeout(): void
+    {
+        $log = tempnam(sys_get_temp_dir(), 'mcp-cancel-');
+        try {
+            $client = $this->connect('cancellation', $this->clientBuilder()->setRequestTimeout(1), env: ['MCP_FIXTURE_LOG' => $log]);
+            $start = microtime(true);
+            try {
+                $client->callTool('slow');
+                $this->fail('The pending request should have timed out.');
+            } catch (TimeoutException) {
+            }
+
+            $this->assertGreaterThanOrEqual(1.0, microtime(true) - $start);
+            $this->assertSame('quick', $client->callTool('fast')->content[0]->text ?? null);
+            $events = $this->events($log);
+            $this->assertSame(['call', 'cancelled', 'call'], array_column($events, 'event'));
+            $this->assertSame($events[0]['id'], $events[1]['id']);
+        } finally {
+            unlink($log);
+        }
+    }
+
     #[TestDox('a pre-cancelled call sends no request')]
     public function testPreCancelledCall(): void
     {
Original file line number	Diff line number	Diff line change
`@@ -49,7 +49,7 @@ public function removePendingRequest(int\|string $requestId): void;`
`49`	`49`	`/**`
`50`	`50`	`* Get all pending requests.`
`51`	`51`	`*`
`52`		`- * @return array<int\|string, array{request_id: int\|string, timestamp: int, timeout: int}>`
	`52`	`+ * @return array<int\|string, array{request_id: int\|string, timestamp: float, timeout: int}>`
`53`	`53`	`*/`
`54`	`54`	`public function getPendingRequests(): array;`
`55`	`55`
Original file line number	Diff line number	Diff line change
`@@ -985,7 +985,7 @@ private function processFiber(): void`
`985`	`985`	`}`
`986`	`986`
`987`	`987`	`// The explicit per-call deadline replaces the default request timeout.`
`988`		`- if (null === ($this->activeSuspend['deadline'] ?? null) && time() - $timestamp >= $timeout) {`
	`988`	`+ if (null === ($this->activeSuspend['deadline'] ?? null) && microtime(true) - $timestamp >= $timeout) {`
`989`	`989`	`$this->logger->warning('Request timed out', ['request_id' => $requestId]);`
`990`	`990`	`$error = Error::forInternalError('Request timed out', $requestId);`
`991`	`991`	`$this->activeSuspend = $this->activeFiber->resume($error);`
Original file line number	Diff line number	Diff line change
`@@ -363,7 +363,7 @@ private function processFiber(): void`
`363`	`363`	`}`
`364`	`364`
`365`	`365`	`// Check timeout`
`366`		`- if (time() - $timestamp >= $timeout) {`
	`366`	`+ if (microtime(true) - $timestamp >= $timeout) {`
`367`	`367`	`$this->logger->warning('Request timed out', ['request_id' => $requestId]);`
`368`	`368`	`$error = Error::forInternalError('Request timed out', $requestId);`
`369`	`369`	`$this->activeSuspend = $this->activeFiber->resume($error);`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,6 @@`
`16`	`16`	`*`
`17`	`17`	`* @author Kyrian Obikwelu <koshnawaza@gmail.com>`
`18`	`18`	`*/`
`19`		`-class TimeoutException extends Exception`
	`19`	`+class TimeoutException extends RequestException`
`20`	`20`	`{`
`21`	`21`	`}`