[Server] Allow context propagation into handler fibers (#670)

* [Server] Allow context propagation into handler fibers

Signed-off-by: bbdu3 <ergouyang854@gamil.com>

* [Server] Free a discarded handler fiber right away

* [Server] Wrap the handler instead of creating the fiber for context propagation

---------

Signed-off-by: bbdu3 <ergouyang854@gamil.com>
Co-authored-by: bbdu3 <ergouyang854@gamil.com>
Co-authored-by: Christopher Hertel <mail@christopher-hertel.de>

Author: 3 people

CHANGELOG.md

@@ -33,6 +33,7 @@ All notable changes to `mcp/sdk` will be documented in this file.
 * Add a `binder` argument to `Builder::setRequestState()` binding the modern era's `requestState` to the request it was minted for, as the 2026-07-28 specification recommends: the binder's value is covered by the state's MAC, and a state echoed on a request that binds to another value is refused like a forged one. `OriginatingRequestBinder` binds the authenticated principal, the method, the tool, prompt or resource, and a digest of the arguments; a token without a subject fails closed, and a `subject` resolver identifies users by another claim. `RequestStateBinderInterface` takes custom bindings. Without a binder, nothing changes.
 * Rotate the `requestState` signing key without failing the calls in flight: `Builder::setRequestState()` and `RequestStateCodec` take a list of keys, the first signing and every key verifying. The wire format is unchanged, and a single key works as before.
 * Log the name of a called tool at info level, so a server logging at INFO shows which tool is called. Its arguments stay at debug level, logged only once the tool is found and its input is valid.
+* Add `Builder::setFiberContext()` and `Mcp\Server\Fiber\FiberContextInterface` to carry execution context, e.g. the active OpenTelemetry context, into handler fibers in both protocol eras.
 * Event loops
   * Add `Builder::setFiberScheduler()` and `Mcp\Server\Fiber\FiberSchedulerInterface`: under an event loop — Revolt (AMPHP), ReactPHP's async — a request handler awaiting I/O suspends its fiber for the loop, and the server now waits through the scheduler until the handler suspends for the server again or returns. The scheduler must wake the server on a later turn of the loop; the guide shows one for Revolt and one for ReactPHP, and the limits under an event loop.
   * Fix the server resuming a request handler's fiber that the runtime had suspended: the handler's await returned early or threw (`Must call resume() or throw() before calling suspend() again`), and the runtime later resumed a fiber that had moved on — under Revolt, terminating the event loop. Without a scheduler, such a handler now fails the request with a `LogicException` naming `Builder::setFiberScheduler()`. `Protocol::__construct()` and `StatelessProtocol::__construct()` take the scheduler as optional last argument.

docs/run/server-builder.md

@@ -347,6 +347,46 @@ A fiber scheduler lets handlers await I/O while the event loop serves other requ
 - A [session lock](sessions.md#concurrent-requests) stays held while a handler awaits I/O. Another request of the
   same session in the same process waits on the event loop until the lock is free. This wait has no timeout. If
   another process holds the lock, the lock backend blocks the event loop while it waits, up to its timeout.
+### Fiber Context
+
+Some libraries keep their context per fiber. For example, OpenTelemetry raises a warning when code reads its context
+in a fiber it doesn't know. Set a fiber context to carry the context of the caller into the fiber of the handler:
+
+```php
+use Mcp\Server;
+use Mcp\Server\Fiber\FiberContextInterface;
+use OpenTelemetry\Context\Context;
+
+final class OpenTelemetryFiberContext implements FiberContextInterface
+{
+    public function wrap(\Closure $handler): \Closure
+    {
+        // runs in the context of the caller
+        $context = Context::getCurrent();
+
+        // runs in the fiber of the handler
+        return static function () use ($context, $handler): mixed {
+            $scope = $context->activate();
+
+            try {
+                return $handler();
+            } finally {
+                $scope->detach();
+            }
+        };
+    }
+}
+
+$server = Server::builder()
+    ->setFiberContext(new OpenTelemetryFiberContext());
+```
+
+The returned closure must call `$handler` once and return its result. The `finally` block also runs when the server
+discards a suspended fiber.
+
+Under an event loop, every request runs in its own fiber, so OpenTelemetry raises the same warning in `wrap()`. Activate
+a context in that fiber first, for example with `Context::getRoot()->activate()`. Fibers that a handler starts itself
+(e.g. with `Amp\async()`) don't get the context.
 
 ## Complete Example
 
@@ -427,6 +467,7 @@ $server = Server::builder()
 | `setContainer()` | container | Set PSR-11 container |
 | `setEventDispatcher()` | eventDispatcher | Set PSR-14 event dispatcher, see [Events](../advanced/events.md) |
 | `setFiberScheduler()` | scheduler | Wait on an event loop (Revolt, ReactPHP) while a handler awaits I/O, see [Fiber Scheduler](#fiber-scheduler) |
+| `setFiberContext()` | context | Carry execution context into handler fibers, see [Fiber Context](#fiber-context) |
 | `setSchemaGenerator()` | schemaGenerator | Replace the generator that builds input schemas from PHP types, see [Schema generation](../servers/schemas.md) |
 | `setSchemaValidator()` | schemaValidator | Replace the validator for tool arguments and structured output, see [Schema generation](../servers/schemas.md) |
 | `setReferenceHandler()` | referenceHandler | Replace the class that calls the handlers of tools, resources and prompts |

src/Server/Builder.php

@@ -45,6 +45,7 @@
 use Mcp\Schema\Tool;
 use Mcp\Schema\ToolAnnotations;
 use Mcp\Server;
+use Mcp\Server\Fiber\FiberContextInterface;
 use Mcp\Server\Fiber\FiberSchedulerInterface;
 use Mcp\Server\Handler\ElementHandlerInterface;
 use Mcp\Server\Handler\Notification\NotificationHandlerInterface;
@@ -142,6 +143,8 @@ final class Builder
 
     private ?FiberSchedulerInterface $fiberScheduler = null;
 
+    private ?FiberContextInterface $fiberContext = null;
+
     /** @var array<string, string> RPC method to the extension identifier defining it */
     private array $extensionMethods = [];
 
@@ -370,6 +373,16 @@ public function setFiberScheduler(FiberSchedulerInterface $scheduler): self
         return $this;
     }
 
+    /**
+     * Carries execution context, e.g. the active OpenTelemetry context, into the fibers request handlers run in.
+     */
+    public function setFiberContext(FiberContextInterface $context): self
+    {
+        $this->fiberContext = $context;
+
+        return $this;
+    }
+
     /**
      * Sets how long, and to whom, this server's answers may be cached (SEP-2549).
      *
@@ -1022,6 +1035,7 @@ public function build(): Server
             requestStateCodec: $this->requestStateCodec(),
             sessionLock: $this->sessionLock,
             fiberScheduler: $this->fiberScheduler,
+            fiberContext: $this->fiberContext,
         );
 
         $modernVersions = $this->modernVersions ?? ProtocolVersion::modernVersions();
@@ -1067,6 +1081,7 @@ public function buildStateless(array $supportedVersions = [ProtocolVersion::V202
             eventDispatcher: $parts['eventDispatcher'],
             requestStateBinder: $this->requestStateBinder,
             fiberScheduler: $this->fiberScheduler,
+            fiberContext: $this->fiberContext,
         );
     }
 

src/Server/Fiber/FiberContextInterface.php

@@ -0,0 +1,31 @@
+<?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\Server\Fiber;
+
+/**
+ * Carries execution context, e.g. the active OpenTelemetry context, into the fibers request handlers run in.
+ *
+ * @author bbdu3 <ergouyang854@gamil.com>
+ */
+interface FiberContextInterface
+{
+    /**
+     * Called in the context of the caller. The returned closure runs in the handler fiber and must call $handler once and return its result.
+     *
+     * @template TReturn
+     *
+     * @param \Closure(): TReturn $handler
+     *
+     * @return \Closure(): TReturn
+     */
+    public function wrap(\Closure $handler): \Closure;
+}

src/Server/Fiber/HandlerFibers.php

@@ -48,9 +48,10 @@ final class HandlerFibers
      *
      * @return \Fiber<mixed, mixed, TReturn, mixed>
      */
-    public static function create(\Closure $handler, ?FiberSchedulerInterface $scheduler = null, ?\Closure $errorForFailure = null, LoggerInterface $logger = new NullLogger()): \Fiber
+    public static function create(\Closure $handler, ?FiberSchedulerInterface $scheduler = null, ?\Closure $errorForFailure = null, LoggerInterface $logger = new NullLogger(), ?FiberContextInterface $context = null): \Fiber
     {
         $state = new HandlerFiberState($scheduler, $errorForFailure, $logger);
+        $handler = $context?->wrap($handler) ?? $handler;
         $fiber = new \Fiber(static function () use ($handler, $state): mixed {
             try {
                 $result = $handler();
@@ -120,19 +121,27 @@ public static function isAbandoned(): bool
      * @throws LogicException when the request of the fiber was already answered, as nobody would resume it
      */
     public static function suspend(object $suspension): mixed
+    {
+        // In its own frame: a local holding the fiber while it suspends would keep it alive until the next GC run.
+        self::parkCurrentFiber($suspension);
+
+        return \Fiber::suspend($suspension);
+    }
+
+    private static function parkCurrentFiber(object $suspension): void
     {
         $fiber = \Fiber::getCurrent();
-        if (null !== $fiber) {
-            $state = self::states()[$fiber] ?? null;
+        if (null === $fiber) {
+            return;
+        }
 
-            if (true === $state?->isAbandoned()) {
-                throw new LogicException('The client gateway cannot be used after the request was answered.');
-            }
+        $state = self::states()[$fiber] ?? null;
 
-            $state?->parked($suspension);
+        if (true === $state?->isAbandoned()) {
+            throw new LogicException('The client gateway cannot be used after the request was answered.');
         }
 
-        return \Fiber::suspend($suspension);
+        $state?->parked($suspension);
     }
 
     /**

src/Server/Protocol.php

@@ -32,6 +32,7 @@
 use Mcp\Schema\Request\InitializeRequest;
 use Mcp\Server\Authorization\AccessToken;
 use Mcp\Server\Fiber\EventLoopSessionLock;
+use Mcp\Server\Fiber\FiberContextInterface;
 use Mcp\Server\Fiber\FiberSchedulerInterface;
 use Mcp\Server\Fiber\HandlerFibers;
 use Mcp\Server\Handler\Notification\NotificationHandlerInterface;
@@ -135,6 +136,7 @@ public function __construct(
         private readonly ?RequestStateCodec $requestStateCodec = null,
         ?SessionLockInterface $sessionLock = null,
         private readonly ?FiberSchedulerInterface $fiberScheduler = null,
+        private readonly ?FiberContextInterface $fiberContext = null,
     ) {
         $this->sessionLock = null !== $sessionLock && null !== $fiberScheduler ? new EventLoopSessionLock($sessionLock, $fiberScheduler) : $sessionLock;
         $this->awaitedRequestIds = new \WeakMap();
@@ -456,7 +458,7 @@ private function handleRequest(TransportInterface $transport, Request $request,
                     }
 
                     return $result;
-                }, $this->fiberScheduler, static fn (\Throwable $e): ?Error => $protocol->get()?->errorForThrowable($e, $request, $session), $this->logger);
+                }, $this->fiberScheduler, static fn (\Throwable $e): ?Error => $protocol->get()?->errorForThrowable($e, $request, $session), $this->logger, $this->fiberContext);
 
                 $result = HandlerFibers::start($fiber);
 

src/Server/Stateless/StatelessProtocol.php

@@ -31,6 +31,7 @@
 use Mcp\Schema\Result\InputRequiredResult;
 use Mcp\Server\Authorization\AccessToken;
 use Mcp\Server\Configuration;
+use Mcp\Server\Fiber\FiberContextInterface;
 use Mcp\Server\Fiber\FiberSchedulerInterface;
 use Mcp\Server\Fiber\HandlerFibers;
 use Mcp\Server\Handler\Request\RequestHandlerInterface;
@@ -117,6 +118,7 @@ public function __construct(
         private readonly ?EventDispatcherInterface $eventDispatcher = null,
         private readonly ?RequestStateBinderInterface $requestStateBinder = null,
         private readonly ?FiberSchedulerInterface $fiberScheduler = null,
+        private readonly ?FiberContextInterface $fiberContext = null,
     ) {
         $this->codec = $codec ?? new Rev2026Codec($configuration->serverInfo, $cachePolicy);
 
@@ -689,7 +691,7 @@ private function unknownMethod(string $method, string|int|null $id): Error
      */
     private function run(RequestHandlerInterface $handler, Request $request, Session $session, RequestMeta $meta): \Generator
     {
-        $fiber = HandlerFibers::create(static fn (): mixed => $handler->handle($request, $session), $this->fiberScheduler, logger: $this->logger);
+        $fiber = HandlerFibers::create(static fn (): mixed => $handler->handle($request, $session), $this->fiberScheduler, logger: $this->logger, context: $this->fiberContext);
         $input = $session->get(InputContext::class);
         // The codec bound to this request, which dispatch() put on the session.
         $codec = $session->get(RequestStateCodec::class);

tests/Unit/Fixtures/RecordingFiberContext.php

@@ -0,0 +1,56 @@
+<?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\Unit\Fixtures;
+
+use Mcp\Exception\LogicException;
+use Mcp\Server\Fiber\FiberContextInterface;
+
+/**
+ * @author bbdu3 <ergouyang854@gamil.com>
+ */
+final class RecordingFiberContext implements FiberContextInterface
+{
+    public string $parent = 'parent';
+    public int $created = 0;
+    public int $released = 0;
+
+    /** @var \WeakMap<object, string> */
+    private \WeakMap $contexts;
+
+    public function __construct()
+    {
+        $this->contexts = new \WeakMap();
+    }
+
+    public function wrap(\Closure $handler): \Closure
+    {
+        $context = $this->current();
+        ++$this->created;
+
+        return function () use ($context, $handler) {
+            $this->contexts[\Fiber::getCurrent() ?? throw new LogicException('No active fiber.')] = $context;
+            try {
+                return $handler();
+            } finally {
+                unset($this->contexts[\Fiber::getCurrent()]);
+                ++$this->released;
+            }
+        };
+    }
+
+    public function current(): string
+    {
+        $fiber = \Fiber::getCurrent();
+
+        return null === $fiber ? $this->parent : ($this->contexts[$fiber] ?? $this->parent);
+    }
+}