[Examples][Tests][Docs] Cover the modern client end to end

An example against the stateless-lifecycle server, an integration test
driving that same server with the SDK's own client, and the conformance
fixture honouring MCP_CONFORMANCE_PROTOCOL_VERSION — without which it
opened every scenario with `initialize`.

The draft client baseline is down to the auth block.

Author: chr-hertel

docs/stateless-lifecycle.md

@@ -299,6 +299,48 @@ A client detects which it is talking to by attempting a modern request and inspe
 `400`: a recognised modern JSON-RPC error means the server is modern and the client should retry with a
 supported version, anything else means it should fall back to `initialize`.
 
+## Writing a client for this revision
+
+One line selects the lifecycle; nothing else about the API changes.
+
+```php
+$client = Client::builder()
+    ->setClientInfo('my-client', '1.0.0')
+    ->setProtocolVersion(ProtocolVersion::V2026_07_28)
+    ->setCapabilities(new ClientCapabilities(elicitation: true))
+    ->addRequestHandler($myElicitationHandler)
+    ->build();
+
+$client->connect(new HttpTransport('https://example.com/mcp'));
+
+$client->callTool('greet', []);
+```
+
+What that changes underneath:
+
+- **No handshake.** `connect()` sends no `initialize`. It asks `server/discover` only for the server's
+  identity, and a server that does not answer it still yields a usable connection — the method is
+  optional. If discovery *does* report `supportedVersions` and the configured revision is not among
+  them, the client moves to a modern revision the server lists, or refuses the connection outright
+  rather than talking past it.
+- **An envelope on every request**, carrying the revision, the declared capabilities and the client
+  identity. The capabilities are what let a server decide, per request, whether it may ask for input.
+- **Headers on every POST** — `MCP-Protocol-Version`, `Mcp-Method`, and `Mcp-Name` where the method
+  addresses a subject. Arguments annotated with `x-mcp-header` are mirrored into `Mcp-Param-*`, which
+  requires the client to have listed the tool first; `tools/list` is what populates that knowledge.
+  A tool whose annotations are malformed is dropped from the listing and refused if called, since the
+  client cannot produce the headers it demands.
+- **Multi round-trip calls are answered by the client.** A result of `resultType: "input_required"` is
+  resolved through the same request handlers that served server-initiated requests in the handshake era,
+  and the call is re-sent with `inputResponses` and the server's `requestState` echoed back byte for
+  byte, under a new JSON-RPC id. The caller sees one call and one result.
+
+Headers are an HTTP concern, so a transport opts into them by implementing `HeaderAwareTransportInterface`;
+`HttpTransport` does, `StdioTransport` has nothing to carry them on. Everything else — the envelope, the
+skipped handshake, the round-trip loop — applies to both.
+
+See `examples/client/stateless_lifecycle_client.php` for a runnable version.
+
 ## What was removed
 
 Answered with `404` and `-32601` by a modern server:

examples/client/README.md

@@ -22,6 +22,19 @@ php -S localhost:8000 examples/server/discovery-calculator/server.php
 php examples/client/http_discovery_calculator.php
 ```
 
+## Modern-era client (2026-07-28)
+
+Speaks the stateless lifecycle: no `initialize`, a `_meta` envelope and SEP-2243 headers on every
+request, and multi round-trip calls answered by the client without the caller noticing.
+
+```bash
+# First, start the matching server
+php -S 127.0.0.1:8000 examples/server/stateless-lifecycle/server.php
+
+# Then run the client
+php examples/client/stateless_lifecycle_client.php
+```
+
 ## Requirements
 
 All examples require the server examples to be available. The STDIO examples spawn the server process, while the HTTP examples connect to a running HTTP server.

examples/client/stateless_lifecycle_client.php

@@ -0,0 +1,109 @@
+<?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.
+ */
+
+/**
+ * Modern-era client (2026-07-28).
+ *
+ * The counterpart to examples/server/stateless-lifecycle. What is worth noticing
+ * is how little of it is about the lifecycle: one call to setProtocolVersion()
+ * and everything else is the same API as any other client.
+ *
+ * Underneath, that one call changes the wire completely:
+ *   - no `initialize` handshake — the connection is usable immediately, and
+ *     `server/discover` is asked only for the server's identity
+ *   - every request carries its own `_meta` envelope naming the revision and
+ *     what this client can be asked to do (SEP-2575)
+ *   - every POST carries `Mcp-Method`, and `Mcp-Name` where the method
+ *     addresses a subject, so an intermediary can route without reading the
+ *     body (SEP-2243)
+ *   - a tool that needs input is answered and retried by the client, so the
+ *     caller sees one call and one result (SEP-2322)
+ *
+ * Usage:
+ *   1. Start the server: php -S 127.0.0.1:8000 examples/server/stateless-lifecycle/server.php
+ *   2. Run this script:  php examples/client/stateless_lifecycle_client.php
+ */
+
+require_once __DIR__.'/../../vendor/autoload.php';
+
+use Mcp\Client;
+use Mcp\Client\Handler\Request\RequestHandlerInterface;
+use Mcp\Client\Transport\HttpTransport;
+use Mcp\Schema\ClientCapabilities;
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Enum\ElicitAction;
+use Mcp\Schema\Enum\ProtocolVersion;
+use Mcp\Schema\JsonRpc\Request;
+use Mcp\Schema\JsonRpc\Response;
+use Mcp\Schema\Request\ElicitRequest;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\ElicitResult;
+
+/**
+ * Answers the server's request for input.
+ *
+ * In this revision the server cannot interrupt a call to ask — it returns the
+ * question as the result. The handler is the same shape either way, which is
+ * the point: a client written for the handshake era keeps working.
+ */
+$answerWithAName = new class implements RequestHandlerInterface {
+    public function supports(Request $request): bool
+    {
+        return $request instanceof ElicitRequest;
+    }
+
+    public function handle(Request $request): Response
+    {
+        assert($request instanceof ElicitRequest);
+
+        echo "  server asked: {$request->message}\n";
+
+        return new Response($request->getId(), new ElicitResult(ElicitAction::Accept, ['name' => 'Ada']));
+    }
+};
+
+$client = Client::builder()
+    ->setClientInfo('stateless-example-client', '1.0.0')
+    // The only line that selects the modern lifecycle.
+    ->setProtocolVersion(ProtocolVersion::V2026_07_28)
+    // Declared in the envelope of every request, so the server knows what it
+    // may ask for before it decides how to answer.
+    ->setCapabilities(new ClientCapabilities(elicitation: true))
+    ->addRequestHandler($answerWithAName)
+    ->build();
+
+$client->connect(new HttpTransport('http://127.0.0.1:8000/'));
+
+printf("Connected to %s (revision %s)\n\n", $client->getServerInfo()?->name, $client->getProtocolVersion()?->value);
+
+echo "Tools:\n";
+foreach ($client->listTools()->tools as $tool) {
+    printf("  %-12s %s\n", $tool->name, $tool->description ?? '');
+}
+
+echo "\nA plain call:\n";
+echo '  '.text($client->callTool('get_weather', ['city' => 'Munich']))."\n";
+
+echo "\nA call the server cannot finish in one round:\n";
+// One call from here. Two on the wire: the server returns its question, the
+// handler above answers it, and the client retries carrying both the answer and
+// the server's sealed `requestState`.
+echo '  '.text($client->callTool('greet', []))."\n";
+
+$client->disconnect();
+
+/** The first block of text in a tool result. */
+function text(CallToolResult $result): string
+{
+    $first = $result->content[0] ?? null;
+
+    return $first instanceof TextContent ? $first->text : '(no text)';
+}

spec-report.md

@@ -11,32 +11,34 @@
 
 The original audit found three structural holes and eight bugs. **All eight bugs and all three structural
 holes are closed**, along with the Tasks extension, the extensions framework, subscriptions delivery,
-request-scoped streaming, the caching policy, deprecations, docs and an end-user example.
+request-scoped streaming, the caching policy, deprecations, docs and end-user examples. The **client** now
+speaks the revision too, so both halves of the SDK are on 2026-07-28.
 
 | | Before | After |
 | --- | --- | --- |
 | Modern conformance (`make conformance-draft-server`) | 138 passed / 3 failed | **151/151** |
 | Handshake conformance (`make conformance-server`) | 39/39 | **80/80** |
 | Server baseline entries | 3 | **0** |
-| Unit tests | 1222 | **1421** |
-| Integration tests | 33 | **43** |
+| Modern client conformance (`make conformance-draft-client`) | not gated | **baseline clean** |
+| Unit tests | 1222 | **1476** |
+| Integration tests | 33 | **47** |
 | Inspector snapshot tests | 97 | **103** |
 | Tasks conformance (`tasks-*`, nine scenarios) | n/a | every failure the runner's core-schema check |
 | PHPStan | 7 pre-existing errors | 7 pre-existing errors |
 
-The server side now passes both revisions outright: the two failures the branch had disclaimed turned out
+Both sides now pass both revisions outright. The two server failures the branch had disclaimed turned out
 to be fixture bugs, not SDK ones — a resource template echoing back its own `{id}` pattern instead of the
 resolved URI, and a `json_schema_2020_12_tool` neither conformance server defined. The check counts jumped
 because the runner is now pinned to a version that carries the 2026-07-28 scenarios and is run with
 `--suite all` on both revisions.
 
 **What is done** — §A lifecycle & transport · §B MRTR · §C headers & metadata · §D results & caching ·
-§E errors & schema · §F subscriptions · §G1 extensions framework · §G2 Tasks · §I1 deprecations · §I3 docs.
+§E errors & schema · §F subscriptions · §G1 extensions framework · §G2 Tasks · §I1 deprecations · §I3 docs ·
+the client side of all of it.
 
 **What remains** — §3.1 MCP Apps ergonomics (an attribute and a scheme check) · §3.2 Authorization (mostly
 blocked: there is no client-side OAuth for those rules to constrain yet) · §3.3 `anyOf` for a union of two
-different array shapes · §3.4 conformance traceability · **§3.5 the client half of 2026-07-28, which is
-untouched**. None is a MUST-level gap for a server implementation.
+different array shapes · §3.4 conformance traceability. None is a MUST-level gap.
 These are tracked in [§3](#3-remaining-work) with the same requirement/evidence/action shape as the original
 audit. Everything else in this document is kept as the record of what was found and how it was closed.
 
@@ -213,25 +215,6 @@ Related: #370 (`additionalProperties` unsupported) and #397 (phpstan/psalm numbe
 to wire SEP traceability files into the runner and surface per-SEP pass rates; #368 is the Tier 2 gap
 analysis, for which this document is input.
 
-### 3.5 The client does not speak 2026-07-28 — P1, no upstream issue yet
-
-Everything above is the **server** half. Gating the client suite on the modern revision (see §4) shows the
-client still opens with `initialize` regardless of the revision it is pointed at, so it never reaches the
-stateless wire at all. Seven scenarios fail on that one root cause:
-
-| Scenario | What is missing |
-| --- | --- |
-| `request-metadata` | the per-request `_meta` envelope, `MCP-Protocol-Version` header, client info and capability declarations (SEP-2575) |
-| `http-standard-headers` | `Mcp-Method` on every POST, `Mcp-Name` on the addressed methods (SEP-2243) |
-| `http-custom-headers` | `x-mcp-header` → `Mcp-Param-*` mirroring, value encoding, the Base64 sentinel, null omission (SEP-2243) |
-| `http-invalid-tool-headers` | refusing a tool whose header annotations do not validate (SEP-2243) |
-| `sep-2322-client-request-state` | echoing `requestState`, a fresh JSON-RPC id per round, parallel isolation (SEP-2322) |
-| `tools_call`, `json-schema-2020-12-preservation` | cascade only — both need a reachable `tools/list` |
-
-The pieces exist server-side (`StatelessProtocol`, `StandardHeaderValidator`, the MRTR machinery), so this
-is a matter of giving the client the same wire, not new protocol work. Baselined per-scenario so the
-entries double as the work list.
-
 ---
 
 ## 4. Verification
@@ -243,16 +226,16 @@ four run in CI — `.github/workflows/pipeline.yaml` matrixes each role over the
 make conformance-server         # handshake endpoint — 80/80
 make conformance-draft-server   # modern endpoint   — 151/151
 make conformance-client         # handshake         — baseline clean (auth stack absent, §3.2)
-make conformance-draft-client   # modern            — baseline clean (§3.2 + §3.5)
+make conformance-draft-client   # modern            — baseline clean (auth stack absent, §3.2)
 
 # Tasks (off the spec timeline, so --force and one scenario at a time):
 npx @modelcontextprotocol/conformance@0.2.0-alpha.11 server --url http://localhost:8000/stateless \
   --scenario tasks-lifecycle --spec-version 2026-07-28 --force
 # Every remaining failure is the runner's wire-schema-valid check applying the
 # *core* schema to an extension result.
 
-vendor/bin/phpunit --testsuite=unit          # 1421
-vendor/bin/phpunit --testsuite=integration   # 43, boots the example over real HTTP
+vendor/bin/phpunit --testsuite=unit          # 1476
+vendor/bin/phpunit --testsuite=integration   # 47, boots the examples over real HTTP
 vendor/bin/phpunit --testsuite=inspector     # 103 (7 skipped); handshake-era examples only
 vendor/bin/phpstan --memory-limit=-1         # 7 pre-existing errors, all alreadyNarrowedType under PHP 8.5
 vendor/bin/php-cs-fixer fix
@@ -264,6 +247,8 @@ the dated revision and `alpha` for the draft one, which is what keeps the pin fr
 
 **The Inspector cannot reach a modern-lifecycle server.** It opens with `initialize`, which this revision
 removed, so `tests/Inspector/` covers the handshake-era examples only. The
-`stateless-lifecycle` example is verified instead by `tests/Integration/StatelessLifecycleTest.php`, which
-drives it over real HTTP the way a conforming client would — discovery, a tool call, both MRTR rounds, a
-tampered `requestState`, and the response stream carrying interleaved progress and log notifications.
+`stateless-lifecycle` example is verified instead by two integration tests, one per direction:
+`StatelessLifecycleTest` drives it with hand-built HTTP the way a conforming client would — discovery, a
+tool call, both MRTR rounds, a tampered `requestState`, and the response stream carrying interleaved
+progress and log notifications — and `StatelessClientTest` drives it with the SDK's own client, which is
+what proves that client is conforming.