PHP Fibers: The Missing Piece for Elegant Cooperative Multitasking

The Fiber Misconception
Understanding Fibers: The Fundamentals
- What is Cooperative Multitasking?
- The Anatomy of a Fiber
Fibers in Asynchronous Libraries
The Real Problem: Client Communication in the MCP SDK
The Thought Process: Why Fibers Work Here
The Implementation: Architecture Overview
The User Experience: What It Looks Like
Under the Hood: The ClientGateway
- The Key Methods
The Protocol: Orchestrating the Dance
Transport #1: StdioTransport (Single Process, Blocking)
Transport #2: StreamableHttpTransport (Multi-Process, HTTP)
Transport #3: ReactPhpHttpTransport (Event-Driven, Async)
The Feedback Loop: Handling Subsequent Suspensions
- The Complete Cycle
The Execution Flow: A Complete Journey
A Note on Exception Handling and Flexibility
- Scenario 1: Unrelated Failures
- Scenario 2: Relevant Failures
Building Your Own: A Practical Example
When Should You Use Fibers?
Conclusion: The Power of Understanding Your Tools
- Final Thoughts
References and Further Reading

If you follow me on Twitter, you might remember a post where I mentioned solving a particularly gnarly problem while working on the official PHP Model Context Protocol (MCP) SDK. I promised a deep dive into how we solved it, and this is it. This is the story of how PHP Fibers saved me from architectural disaster while building the client communication feature for the PHP MCP SDK.

The feature was introduced in PR #109, and the implementation showcases one of the most elegant uses of PHP Fibers I've encountered. But this isn't just a story about one problem. It's about a powerful PHP feature that's been hiding in plain sight since PHP 8.1, largely misunderstood and underutilized. When I finally understood what Fibers could do, it felt like discovering a secret passage in a room I'd been stuck in for hours.

Here's what you'll learn in this article:

What PHP Fibers really are (and what they're not)
When and why you should use them
How to think about cooperative multitasking
A Real-world implementation using Fibers
Patterns you can use in your own code

This is going to be a long one. Grab a drink, settle in, and let's talk PHP Fibers.

The Fiber Misconception

Let's start by addressing the elephant in the room: PHP Fibers are NOT async PHP. They're not parallelism. They're not threads. They're not about making PHP run multiple things at once.

When PHP 8.1 dropped with Fiber support in November 2021, many developers (myself included) looked at it with confusion. "Great, another async thing?" we thought. The confusion was understandable because the most visible use of Fibers has been in asynchronous libraries like ReactPHP and AmPHP.

ReactPHP even has a package called async that uses Fibers to make asynchronous code look synchronous:

// Before Fibers: Callback hell
$promise->then(function($result) {
    return anotherAsyncCall($result);
})->then(function($finalResult) {
    echo $finalResult;
});
 
// With Fibers: Looks synchronous!
$result = await($promise);
$finalResult = await(anotherAsyncCall($result));
echo $finalResult;

Seeing this, it's easy to think "Fibers = async magic." But that's missing the bigger picture.

Fibers are about cooperative multitasking. They're about giving your code the ability to pause execution, do something else, and then come back exactly where you left off, with all your variables, your call stack and your execution context perfectly preserved.

Yes, this is incredibly useful for async libraries. But it's just as useful in purely synchronous code when you need controlled interruption and resumption. And that's where most PHP developers miss the opportunity.

The slow adoption of Fibers isn't because they're not useful. It's because most developers don't know when to use them. And that's exactly what this article is going to fix.

Understanding Fibers: The Fundamentals

Before we get into complex examples, let's build a solid foundation. What exactly is a Fiber, and how does it work?

What is Cooperative Multitasking?

A good analogy to understand Fibers is to think of a standard PHP script as a train on a single track. It goes from Station A to Station B. It typically cannot stop until it reaches B. A Fiber allows the train to stop in the middle of the track, let the passengers off (or allow the passengers take some bathroom break), and while at it, even let another train use the track for a bit, and then resume exactly where it left off with all its luggage (variables and memory state) intact.

Another analogy is to imagine you're reading a book while cooking dinner. You read a few pages, then when the timer beeps, you bookmark your page, stir the pot, and go back to reading exactly where you left off. That's cooperative multitasking.

The key word is cooperative. You (the reader/cook) decide when to switch tasks. Nobody interrupts you forcefully, instead you yield control willingly when it makes sense.

In programming terms:

Preemptive multitasking: The operating system interrupts your code forcefully (threads, processes)
Cooperative multitasking: Your code decides when to yield control (coroutines, fibers)

Fibers are PHP's implementation of cooperative multitasking. They let you:

Start executing a piece of code
Pause it at any point (suspend)
Do other things
Resume exactly where you left off
Repeat as many times as needed

The Anatomy of a Fiber

Let's look at a simple example:

<?php
 
$fiber = new Fiber(function(): string {
    echo "1. Fiber started\n";
 
    $value = Fiber::suspend('pause-1');
    echo "3. Fiber resumed with: $value\n";
 
    $value2 = Fiber::suspend('pause-2');
    echo "5. Fiber resumed again with: $value2\n";
 
    return 'final-result';
});
 
echo "0. Before starting fiber\n";
 
$suspended1 = $fiber->start();
echo "2. Fiber suspended with: $suspended1\n";
 
$suspended2 = $fiber->resume('data-1');
echo "4. Fiber suspended again with: $suspended2\n";
 
$result = $fiber->resume('data-2');
echo "6. Fiber returned: $result\n";

Output:

0. Before starting fiber
1. Fiber started
2. Fiber suspended with: pause-1
3. Fiber resumed with: data-1
4. Fiber suspended again with: pause-2
5. Fiber resumed again with: data-2
6. Fiber returned: final-result

I included the numbers so you see how execution jumps in and out of the Fiber. Suspend makes it jump out of the Fiber, resume makes it jump back in! For better clarity, let's break down what happened:

Creation: new Fiber(function() {...}) creates a fiber but doesn't execute it yet
Start: $fiber->start() begins execution until the first Fiber::suspend()
Suspend: Fiber::suspend('pause-1') pauses execution and returns control to the caller
Resume: $fiber->resume('data-1') continues execution from where it suspended
Return: When the fiber completes, resume() returns the final value

The magic is in the execution context switching. When the fiber suspends:

All local variables are preserved
The call stack is saved
Execution jumps back to whoever called start() or resume()
The value passed to suspend() is returned to the caller

When you resume:

Execution jumps back into the fiber
The value passed to resume() becomes the return value of suspend()
Everything continues as if nothing happened

One crucial insight that makes Fibers powerful: code running inside a fiber doesn't need to know it's in a fiber.

Look at this:

function processData(int $id): string {
    $data = fetchData($id);  // This might suspend!
    $result = transform($data);  // This might also suspend!
    return $result;
}
 
// Called inside a fiber
$fiber = new Fiber(fn() => processData(42));
$fiber->start();

From processData's perspective, it's just calling functions and returning results. It doesn't know that fetchData() and transform() might be suspending the fiber behind the scenes. The complexity is hidden.

This is what makes Fibers perfect for building clean APIs that hide complex behavior.

Fibers in Asynchronous Libraries

Now that we understand the basics, let's see why some people may associate Fibers with async code. This will also show us a concrete use case before we tackle the main problem.

The Async Problem

Asynchronous programming in PHP traditionally looks like this:

// Using promises (before Fibers)
function fetchUserData(int $userId): PromiseInterface {
    return $this->httpClient->getAsync("/users/$userId")
        ->then(function($response) {
            return json_decode($response->getBody());
        })
        ->then(function($userData) use ($userId) {
            return $this->cache->setAsync("user:$userId", $userData);
        })
        ->then(function() use ($userId) {
            return "User $userId cached";
        });
}

This works, but it's hard to read and reason about. Error handling with catch() gets messy. Debugging is painful. And it doesn't "feel" like PHP.

The Fiber Solution

With Fibers, libraries like ReactPHP can offer this:

// Using Fibers (after PHP 8.1)
function fetchUserData(int $userId): string {
    $response = await($this->httpClient->getAsync("/users/$userId"));
 
    $userData = json_decode($response->getBody());
 
    await($this->cache->setAsync("user:$userId", $userData));
 
    return "User $userId cached";
}

Much better! But how does await() work? Let me show you a simplified version:

namespace React\Async;
 
function await(PromiseInterface $promise): mixed {
    // Suspend the fiber and register promise callbacks
    $result = Fiber::suspend([
        'type' => 'await',
        'promise' => $promise
    ]);
 
    // When resumed, we'll have the result or exception
    if ($result instanceof \Throwable) {
        throw $result;
    }
 
    return $result;
}

And if you're feeling fancy, tools like PHPStan let you sprinkle in a little generics magic so await() knows exactly what's coming back from your Promise. Strong static analysis that feels like wizardry. How cool is that?

Here's what happens:

User code calls await($promise) (inside a fiber)
await() calls Fiber::suspend() with the promise
The event loop sees the suspended fiber and promise
The event loop continues processing other things as usual while the fiber is suspended
When the promise resolves, the loop calls $fiber->resume($value)
Execution continues in await(), which returns the value
User code gets the value as if it was synchronous!

The fiber suspends while waiting for the async operation, but the user's code looks completely synchronous.

Taking It Further: Truly Transparent Async

But we can go even further! Libraries like AmPHP take this to the next level by creating fiber-aware wrappers around async operations. Instead of having separate getAsync() and await() calls, you just have methods that look completely synchronous:

// AmPHP approach: No await() needed!
function fetchUserData(int $userId): string {
    $response = $this->httpClient->get("/users/$userId");  // Looks sync, is async!
 
    $userData = json_decode($response->getBody());
 
    $this->cache->set("user:$userId", $userData);  // Looks sync, is async!
 
    return "User $userId cached";
}

Wait, what? No await() calls? How does this work?

The magic is that get() and set() internally use Fibers. Here's a simplified example:

class HttpClient {
    public function get(string $url): Response {
        // Create the async operation
        $promise = $this->performAsyncRequest('GET', $url);
 
        // Suspend the current fiber and pass the promise to the event loop
        $response = \Fiber::suspend([
            'type' => 'await',
            'promise' => $promise
        ]);
 
        if ($response instanceof \Throwable) {
            throw $response;
        }
 
        return $response;
    }
}

From the user's perspective, they just called get() and got a response. They have no idea it was async.

This is the epitome of Fibers: making async operations completely transparent. The user writes what looks like blocking, synchronous PHP code. The library handles all the async complexity using Fibers behind the scenes.

Comparing the Approaches

Let's see the evolution:

// 1. Traditional async with promises (no Fibers)
$promise = $this->httpClient->getAsync("/users/$userId")
    ->then(fn($response) => json_decode($response->getBody()))
    ->then(fn($userData) => $this->cache->setAsync("user:$userId", $userData))
    ->then(fn() => "User $userId cached");
 
// 2. Async with await() helper (using Fibers)
$response = await($this->httpClient->getAsync("/users/$userId"));
$userData = json_decode($response->getBody());
await($this->cache->setAsync("user:$userId", $userData));
return "User $userId cached";
 
// 3. Fully transparent async (Fibers hidden in library)
$response = $this->httpClient->get("/users/$userId");
$userData = json_decode($response->getBody());
$this->cache->set("user:$userId", $userData);
return "User $userId cached";

Notice how approach #3 looks exactly like synchronous code? That's the power of Fibers when used correctly. The library developer handles the complexity once. Every user benefits from a clean, synchronous-looking API that's actually asynchronous under the hood.

Why This Led to the Misconception

Because the most visible use of Fibers was making async code look sync, developers assumed Fibers were the async mechanism. But Fibers themselves don't do anything asynchronous. They just provide the suspension/resumption mechanism that makes sync-looking async code possible.

The event loop is still doing the actual async work. Fibers just make the API nicer.

This distinction is crucial: Fibers are a tool for managing execution flow, not for achieving parallelism or asynchrony.

The Real Problem: Client Communication in the MCP SDK

Now let's get to the problem that inspired this article. I was working on the PHP implementation of the Model Context Protocol (MCP), and we hit a design challenge that seemed impossible to solve elegantly.

What is MCP?

The Model Context Protocol is a standard for connecting AI assistants (like Claude) with external tools and data sources.

An MCP server exposes:

Tools: Functions the AI can call (e.g., "search database", "send email")
Resources: Data the AI can read (e.g., "project files", "API documentation")
Prompts: Templates the AI can use

The protocol is bi-directional JSON-RPC over different transports (STDIO, HTTP + SSE, Custom).

The Challenge

The MCP specification includes features for servers to communicate back to clients during request handling:

Logging: Send log messages to the client
Progress: Update the client on long-running operations
Sampling: Ask the client to generate text with its LLM

These aren't just response types. Nope, thing is, they need to happen during the execution of a tool. For example:

Client: "Hey server, run the 'analyze_dataset' tool"
Server: "Starting..." [sends log]
Server: "25% complete" [sends progress]
Server: "50% complete" [sends progress]
Server: "Generating summary, need your LLM" [sends sampling request]
Client: "Here's the generated summary" [responds to sampling]
Server: "Done! Here's the full result" [sends final response]

The server needs to:

Send messages mid-execution
Wait for responses from the client
Continue execution after receiving responses
Make all this feel natural to write

The API Requirement

One of our priorities when it comes to the MCP SDK is for it to be extremely easy to use. We wanted developers to write tools like this:

$server->addTool(
    function (string $dataset, ClientGateway $client): array {
        $client->log(LoggingLevel::Info, "Starting analysis");
 
        foreach ($steps as $step) {
            $client->progress($progress, 1, $step);
            doWork($step);
        }
 
        $summary = $client->sample("Summarize this data: ...");
 
        return ['status' => 'complete', 'summary' => $summary];
    },
    name: 'analyze_dataset'
);

Look at that code. It's beautiful. It's simple. It looks completely synchronous. There's no callbacks, no promises, no async/await syntax, no yield generators. Just regular PHP.

But under the hood, this needs to:

Send JSON-RPC notifications to the client (log, progress)
Send JSON-RPC requests and wait for responses (sampling)
Work with both with any transport, blocking or not!
Work whether you're using vanilla PHP, ReactPHP, Swoole, or RoadRunner

How do you make that work?

Why Traditional Approaches Wouldn't Work

I spent hours considering different solutions:

Option 1: Make Everything Async

// Promise-based approach - nested and messy
$server->addTool(function (string $dataset, $client) {
    return $client->logAsync(LoggingLevel::Info, "Starting analysis")
        ->then(function() use ($client) {
            return $client->progressAsync(0.33, 1, "Step 1");
        })
        ->then(function() use ($client) {
            return $client->progressAsync(0.66, 1, "Step 2");
        })
        ->then(function() use ($client) {
            return $client->sampleAsync("Summarize...");
        })
        ->then(function($summary) {
            return ['status' => 'complete', 'summary' => $summary];
        });
});

The callback nesting gets unwieldy fast. Even if we used await() helpers to simplify it:

$server->addTool(function (string $dataset, $client) {
    await($client->logAsync(LoggingLevel::Info, "Starting"));
    await($client->progressAsync(0.33, 1, "Step 1"));
    await($client->progressAsync(0.66, 1, "Step 2"));
    $summary = await($client->sampleAsync("Summarize..."));
    return ['status' => 'complete', 'summary' => $summary];
});

This forces everyone to learn async PHP. It makes async libraries a core dependency and limits the SDK to the async runtime we chose to go with. Unlike PSR-7 for server requests and responses, there's no standard for event loops or async runtime in PHP so that vendor lock in was not an option. Also it's an overkill for simple tools. Rejected.

Option 2: Callbacks

// Callback hell alert!
$server->addTool(function (string $dataset, $client) {
    $client->log(..., function() use ($client) {
        $client->progress(..., function() use ($client) {
            $client->sample(..., function($summary) {
                return ['summary' => $summary];
            });
        });
    });
});

Nobody wants this. No further explanation needed. Rejected.

Option 3: State Machines and Serialization

What if we track execution state and re-execute the handler from checkpoints?

// Pseudo-code
if ($state->step === 0) {
    $client->log(...);
    $state->step = 1;
    return $state->serialize();
}
if ($state->step === 1) {
    $client->progress(...);
    $state->step = 2;
    return $state->serialize();
}
// ... and so on

This is insanely complex. Even if we abstract part of it and allow the user write synchronous code, there's a lot of work to do to track the state. How do you serialize closures? How do you restore local variables? How do you handle loops? This would require completely changing how users write tools. Rejected.

Option 4: Generators with yield

$server->addTool(function (string $dataset, $client) {
    yield $client->log(...);
    yield $client->progress(...);
    $summary = yield $client->sample(...);
    return ['summary' => $summary];
});

This is closer, but generators are limited. You can't yield from nested function calls easily. The syntax is awkward. And users need to understand generators. Not ideal, but possible.

Option 5: PHP Fibers

What if the suspension/resumption happens invisibly? What if $client->log() looks like a normal method call, but behind the scenes it suspends the fiber, sends the message, and resumes?

// What users write (looks synchronous!)
$server->addTool(function (string $dataset, $client) {
    $client->log(...);  // Suspends internally
    $client->progress(...);  // Suspends internally
    $summary = $client->sample(...);  // Suspends and waits
    return ['summary' => $summary];
});

This is it. This is the solution. Users write normal PHP. The SDK handles all the complexity.

The "Aha!" Moment

The moment I realized Fibers were the answer, everything clicked. Here's why they're perfect:

Transparent: User code doesn't need to know about fibers
Flexible: Works with any transport (blocking or non-blocking)
Simple: The API is just regular method calls
Powerful: Full control over execution flow
Universal: Works with sync PHP, async PHP, any runtime

Fibers let us hide the complexity of bidirectional communication behind a clean, synchronous-looking API. The user writes simple functions. The SDK manages the fiber lifecycle. The transports handle the actual I/O.

It's the perfect separation of concerns.

The Thought Process: Why Fibers Work Here

Let me walk you through why Fibers are uniquely suited to this problem.

The Core Challenge

When a tool handler calls $client->log(), we need to:

Pause the handler's execution
Send a JSON-RPC notification to the client (the mechanism depends on the transport)
Resume the handler immediately (logging doesn't wait)

When a tool handler calls $client->sample(), we need to:

Pause the handler's execution
Send a JSON-RPC request to the client (the mechanism depends on the transport)
Wait for the client's response (how we receive the response is also transport-dependent)
Resume the handler with the response

The key insight: we need to leave the handler's execution context, do something else, then return to it at a particular point. And we need to be able to do that as many times as we want. That's exactly what Fibers provide.

The Architecture

The solution has three layers:

ClientGateway (user-facing API)
- Methods like log(), progress(), sample()
- Internally calls Fiber::suspend() with message data
- Returns the response when resumed
Protocol (orchestration layer)
- Wraps handler execution in a Fiber
- Detects when the Fiber suspends
- Extracts the suspended value (notification or request)
- Hands off the Fiber to the Transport
Transport (I/O layer)
- Takes ownership of suspended Fibers
- Sends messages to the client (responses, requests & notifications)
- Waits for responses (if needed)
- Resumes Fibers when ready

Each layer has a clear responsibility. The magic is in how they coordinate.

Why It Works with Both Sync and Async

The beauty of this approach is that Fibers are transport-agnostic. The suspension/resumption mechanism is the same whether you're using:

Stdio (blocking, single process) - Part of the official SDK
HTTP with PHP-FPM (stateless, multi-process) - Part of the official SDK
ReactPHP (non-blocking, event-driven) - External example showing async compatibility
Swoole (coroutine-based) - Possible with the same architecture

The transport decides when to resume the fiber based on its execution model. The fiber itself doesn't care. It just suspends and waits.

For blocking transports, resumption happens in a loop in the same process. For non-blocking transports, resumption happens via event loop callbacks. For multi-process transports, resumption happens when responses are pulled from shared sessions. The Fiber cares less.

The Implementation: Architecture Overview

Now let's look into the actual implementation. I'll show you some real code from the PHP MCP SDK and explain how everything fits together.

The Three Key Components

The system has three main parts:

User Code (Handler)
       ↓
ClientGateway (API)
       ↓
   Protocol (Orchestrator)
       ↓
   Transport (I/O)

The Handoff: Protocol to Transport

This is the crucial moment. Here's the simplified flow in the Protocol:

src/Server/Protocol.php

// Protocol::handleRequest()
public function handleRequest(Request $request, SessionInterface $session): void {
    $handler = $this->findHandler($request);
 
    // Execute handler inside a fiber!
    $fiber = new \Fiber(fn() => $handler->handle($request, $session));
 
    $result = $fiber->start();
 
    if ($fiber->isSuspended()) {
        // Fiber yielded something! Extract it.
        if ($result['type'] === 'notification') {
            $this->sendNotification($result['notification'], $session);
        } elseif ($result['type'] === 'request') {
            $this->sendRequest($result['request'], $result['timeout'], $session);
        }
 
        // Give the fiber to the transport
        $this->transport->attachFiberToSession($fiber, $session->getId());
    } else {
        // Fiber completed without suspending
        $finalResult = $fiber->getReturn();
        $this->sendResponse($finalResult, $session);
    }
}

The protocol starts the fiber and checks if it suspended. If it did, the protocol extracts what was suspended (notification or request), queues it for sending, and hands the fiber to the transport. We'll discuss this in detail in a sec. Let's move on for now.

From this point, the transport owns the fiber's lifecycle. Further suspensions and resumptions are handled by the Transport.

Transport Responsibilities

Each transport must:

Accept fibers from the protocol
Send queued messages to clients
Receive client responses
Resume fibers at the appropriate time
Handle fiber termination

Different transports do this differently based on their execution model. Let's look at each one.

The User Experience: What It Looks Like

Before we dive deep into transport implementations, let's see what the end result looks like from a user's perspective. This is important because it shows why the complexity is worth it.

Example 1: Simple Progress Updates

Here's a real example from the MCP SDK docs:

server.php

$server->addTool(
    function (string $dataset, ClientGateway $client): array {
        $client->log(LoggingLevel::Info, "Running quality checks on dataset: $dataset");
 
        $tasks = [
            'Validating schema',
            'Scanning for anomalies',
            'Reviewing statistical summary',
        ];
 
        foreach ($tasks as $index => $task) {
            $progress = ($index + 1) / count($tasks);
            $client->progress($progress, 1, $task);
 
            usleep(140_000); // Simulate work
        }
 
        $client->log(LoggingLevel::Info, "Dataset $dataset passed automated checks");
 
        return [
            'dataset' => $dataset,
            'status' => 'passed',
            'notes' => 'No significant issues detected',
        ];
    },
    name: 'run_dataset_quality_checks',
    description: 'Perform dataset quality checks with progress updates'
);

Look at this tool code. It's just a regular function. It loops over tasks. It calls $client->progress() like it's a normal method. There's no indication that this is doing complex bidirectional communication.

But here's what's actually happening:

The handler starts (inside a fiber)
$client->log() suspends the fiber
The transport sends the log notification
The fiber resumes
The loop starts
First $client->progress() suspends the fiber
The transport sends the progress notification
The fiber resumes
usleep() runs (still in the fiber)
Second $client->progress() suspends again
... and so on

Each suspension and resumption is invisible to the user. The code looks and behaves like synchronous PHP. The execution keeps jumping back and forth betweeen the transport's loop (who is now the owner) and the tool's handler,and each time it comes back to the handler, it comes back at the perfect spot and resumes (even within the foreach loop). Define beauty please!!

Example 2: Requesting LLM Sampling

Here's a more complex example that actually waits for a response:

app/Tools/IncidentCordinator.php

class IncidentCoordinator implements ClientAwareInterface {
    use ClientAwareTrait;  // Provides $this->log and $this->progress
 
    #[McpTool('coordinate_incident_response', 'Coordinate incident response')]
    public function coordinateIncident(string $incidentTitle): array {
        $this->log(LoggingLevel::Warning, "Incident triage started: $incidentTitle");
 
        $steps = [
            'Collecting telemetry',
            'Assessing scope',
            'Coordinating responders',
        ];
 
        foreach ($steps as $index => $step) {
            $progress = ($index + 1) / count($steps);
            $this->progress($progress, 1, $step);
            usleep(180_000);
        }
 
        // Ask the client's LLM to generate a response strategy
        $prompt = "Provide a concise response strategy for incident \"$incidentTitle\"
                   based on: " . implode(', ', $steps);
 
        $result = $this->sample($prompt, 350, 90, ['temperature' => 0.5]);
 
        $recommendation = $result->content instanceof TextContent
            ? trim($result->content->text)
            : '';
 
        $this->log(LoggingLevel::Info, "Incident triage completed");
 
        return [
            'incident' => $incidentTitle,
            'recommended_actions' => $recommendation,
            'model' => $result->model,
        ];
    }
}

This is even more magical. The sample() call:

Suspends the fiber with a sampling request
The transport sends the request to the client
The transport waits for the client to respond (how the response comes is up to the transport, and this could take seconds!)
When the response arrives, the transport resumes the fiber with it
$result contains the response, and execution continues

From the method's perspective, it made a synchronous call and got a result. Behind the scenes:

The fiber was suspended
Control went back to the transport's event loop
The transport handled other things (maybe other requests)
When the response came in (possibly from another HTTP request/process), the fiber resumed
The method continued as if nothing happened

This is cooperative multitasking in action. And the developer writing this tool has no idea it's happening.

The ClientAwareTrait Pattern

Notice the ClientAwareTrait in the example above. This is one of two ways to access the ClientGateway:

Method 1: Type-hint in the handler

#[McpTool('my_tool')]
public function myTool(string $input, ClientGateway $client): string {
    $client->log(...);
    return $result;
}

The SDK detects the ClientGateway parameter and injects it automatically.

Method 2: Implement ClientAwareInterface

class MyService implements ClientAwareInterface {
    use ClientAwareTrait;  // Provides setClient() and helper methods
 
    #[McpTool('my_tool')]
    public function myTool(string $input): string {
        $this->log(...);  // ClientAwareTrait provides this
        $this->progress(...);
        $result = $this->sample(...);
        return $result;
    }
}

The SDK calls setClient() before invoking the handler, and the trait provides convenient methods like log(), progress(), sample() that internally use the client.

Both approaches give you the same power. The user chooses based on preference.

Under the Hood: The ClientGateway

Now let's peel back the first layer and see how the ClientGateway works. This is the API users interact with. It's surprisingly (not so surprisingly) simple, but super powerful.

Here's the actual implementation (simplified for clarity):

src/Server/ClientGateway.php

final class ClientGateway {
    public function __construct(
        private readonly SessionInterface $session,
    ) {}
 
    /**
     * Send a notification to the client (fire and forget).
     */
    public function notify(Notification $notification): void {
        \Fiber::suspend([
            'type' => 'notification',
            'notification' => $notification,
            'session_id' => $this->session->getId()->toRfc4122(),
        ]);
    }
 
    /**
     * Send a log message to the client.
     */
    public function log(LoggingLevel $level, mixed $data, ?string $logger = null): void {
        $this->notify(new LoggingMessageNotification($level, $data, $logger));
    }
 
    /**
     * Send a progress update to the client.
     */
    public function progress(float $progress, ?float $total = null, ?string $message = null): void {
        $meta = $this->session->get(Protocol::SESSION_ACTIVE_REQUEST_META, []);
        $progressToken = $meta['progressToken'] ?? null;
 
        if (null === $progressToken) {
            // Client didn't ask for progress, skip it
            return;
        }
 
        $this->notify(new ProgressNotification($progressToken, $progress, $total, $message));
    }
 
    /**
     * Request LLM sampling from the client.
     */
    public function sample(
        array|Content|string $message,
        int $maxTokens = 1000,
        int $timeout = 120,
        array $options = []
    ): CreateSamplingMessageResult {
        // Prepare the message
        if (is_string($message)) {
            $message = new TextContent($message);
        }
        if ($message instanceof Content) {
            $message = [new SamplingMessage(Role::User, $message)];
        }
 
        $request = new CreateSamplingMessageRequest(
            messages: $message,
            maxTokens: $maxTokens,
            preferences: $options['preferences'] ?? null,
            systemPrompt: $options['systemPrompt'] ?? null,
            temperature: $options['temperature'] ?? null,
            // ... other options
        );
 
        // Send request and wait for response
        $response = $this->request($request, $timeout);
 
        if ($response instanceof Error) {
            throw new ClientException($response);
        }
 
        return CreateSamplingMessageResult::fromArray($response->result);
    }
 
    /**
     * Send a request to the client and wait for response.
     */
    private function request(Request $request, int $timeout = 120): Response|Error {
        $response = \Fiber::suspend([
            'type' => 'request',
            'request' => $request,
            'session_id' => $this->session->getId()->toRfc4122(),
            'timeout' => $timeout,
        ]);
 
        if (!$response instanceof Response && !$response instanceof Error) {
            throw new RuntimeException('Transport returned unexpected payload');
        }
 
        return $response;
    }
}

The Key Methods

notify() - The simplest case:

public function notify(Notification $notification): void {
    \Fiber::suspend([
        'type' => 'notification',
        'notification' => $notification,
        'session_id' => $this->session->getId()->toRfc4122(),
    ]);
}

This suspends the current fiber with a data structure indicating:

It's a notification (no response needed)
What notification to send
Which session it belongs to

The fiber will be resumed immediately after the notification is queued.

request() - The complex case:

private function request(Request $request, int $timeout = 120): Response|Error {
    $response = \Fiber::suspend([
        'type' => 'request',
        'request' => $request,
        'session_id' => $this->session->getId()->toRfc4122(),
        'timeout' => $timeout,
    ]);
 
    return $response;
}

This suspends the fiber with a data structure indicating:

It's a request (response expected)
What request to send
How long to wait for a response

The fiber will NOT be resumed until:

The client sends a response, OR
The timeout expires

When resumed, the value passed to $fiber->resume($value) becomes the return value of Fiber::suspend(). So $response will be either a Response object (success) or an Error object (failure/timeout).

The Protocol: Orchestrating the Dance

The Protocol is the orchestration layer that sits between the user-facing API (ClientGateway) and the transport layer. We've already seen a simplified view of the handoff in the Architecture Overview section. Now let's dig deeper into how the Protocol actually orchestrates the entire flow.

The Flow in Detail

Building on the simplified version we saw earlier, here's the complete flow when a request comes in:

Find the handler: The Protocol iterates through registered handlers to find one that supports this specific request type. Each handler declares what methods it supports (e.g., tools/call, prompts/get, etc.). If no handler is found, return a "method not found" error immediately.
Wrap in fiber and start execution:
```
$fiber = new \Fiber(fn() => $handler->handle($request, $session));
$result = $fiber->start();
```
The magic starts here. The handler executes inside a brand new fiber. If the handler calls $client->log() or $client->sample(), those methods will call Fiber::suspend(), which bubbles up to this point. The $result contains whatever was passed to suspend().
Check suspension status: After starting the fiber, the Protocol checks $fiber->isSuspended(). This tells us if the handler is paused (waiting for something) or completed (returned a value).
If suspended - Extract the yielded value: When suspended, $result contains an array like ['type' => 'notification', 'notification' => $obj] or ['type' => 'request', 'request' => $obj, 'timeout' => 120]. The Protocol examines this structure to understand what the handler wants to do.
Queue the message: For notifications, the Protocol calls sendNotification() which queues the message in the session. For requests, it calls sendRequest() which queues the message in the session too, but with extra infomation to track it as "pending" with a timestamp and timeout.
Hand off to transport: This is the crucial moment:
```
$this->transport->attachFiberToSession($fiber, $session->getId());
```
The Protocol gives the suspended fiber to the transport and returns. From this point forward, the transport owns the fiber. The Protocol's job is done until the next request comes in.
If not suspended - Send final response: If the handler never called any client communication methods, the fiber completes immediately. The Protocol retrieves the return value with $fiber->getReturn() and sends it as the final response.

Why the Protocol Doesn't Resume Fibers

Notice that the protocol never calls $fiber->resume(). Could it? Technically, yes. The protocol could send a notification, then immediately resume the fiber. Or wait for a response, then resume. The main reason it doesn't is because different transports have wildly different I/O models.

The StdioTransport runs a blocking loop that continuously reads stdin, processes fibers, and writes to stdout
The StreamableHttpTransport opens an SSE stream that blocks the entire process, creating its own event loop that manages everything
The ReactPHP transport uses a non-blocking event loop with timers and callbacks

The key insight: sending messages and waiting for responses are transport-specific operations that might block.

For example, when the HTTP transport opens an SSE stream, that stream blocks the process. The only thing that can run is the SSE loop. Control oscillates between the transport's loop and the handler execution (via fiber suspend/resume). If the Protocol tried to manage resumption, it would need to understand each transport's execution model.

By giving the transport ownership of the fiber after the first suspension, the transport can:

Send messages according to its I/O model (blocking, non-blocking, async)
Wait for responses using its own mechanisms (polling sessions, event callbacks, timers)
Resume the fiber when it's ready, not when the protocol thinks it should
Handle subsequent suspensions that might occur after resumption

This isn't a fiber limitation, just an architectural decision. The protocol handles request/response semantics. The transport handles I/O and fiber lifecycle. Clean separation.

Handling Responses from the Client

When the client sends a response back (to a sampling request, for example), it comes in as a new message. The protocol receives it and stores it in the session:

src/Server/Protocol.php

private function handleResponse(Response|Error $response, SessionInterface $session): void {
    $this->logger->info('Handling response from client.', ['response' => $response]);
 
    $messageId = $response->getId();
 
    // Store the response in the session
    $session->set(self::SESSION_RESPONSES . ".{$messageId}", $response->jsonSerialize());
    $session->forget(self::SESSION_ACTIVE_REQUEST_META);
 
    $this->logger->info('Client response stored in session', [
        'message_id' => $messageId,
    ]);
}

You'll notice that the protocol doesn't resume the fiber directly. Why? Because the protocol doesn't own the fiber anymore — the transport does. So when a client sends a response, the transport retrieves it from the session and calls $fiber->resume($response).

The transport is responsible for:

Checking the session for responses
Matching responses to pending requests
Resuming the fiber with the response
Handling the fiber until it terminates

Different transports do this differently based on their I/O model. Let's see how.

Transport #1: StdioTransport (Single Process, Blocking)

The StdioTransport is the simplest case: single process, blocking I/O, stdin/stdout.

The Challenge

With stdio:

We have one process
We need to read from stdin (blocking operation)
We need to manage suspended fibers
We need to send messages to stdout
We need to wait for client responses

How do you do all this without freezing?