[Server][Tests] Validate the standard MCP request headers (SEP-2243) (#445)

The revision puts the method, the subject name and the mirrored arguments in
headers so an intermediary can route and cache without parsing the body. A
header that contradicts the body it travels with therefore has to be
refused, not ignored: StandardHeaderValidator compares each against the
request and answers -32020 on a mismatch.

Set with Builder::setHeaderValidator(); a transport with no header layer is
unaffected.

tests/Conformance/conformance-baseline-2026-07-28.yml

@@ -13,21 +13,10 @@
 #   make conformance-draft-server
 #
 # Absent by design, because they pass in full: server-stateless (the SEP-2575
-# lifecycle), caching (SEP-2549 hints), and every wire-schema-valid check bar
-# one noted below.
+# lifecycle), caching (SEP-2549 hints), both SEP-2243 header-validation
+# scenarios, and every wire-schema-valid check bar one noted below.
 
 server:
-  # --- SEP-2243: standard HTTP headers ---------------------------------------
-  # Mcp-Method / Mcp-Name validation and the X-MCP-* parameter rules are not
-  # implemented. Self-contained and the largest remaining block; a good next
-  # chunk after MRTR.
-  - http-header-validation:sep-2243-server-reject-invalid-headers
-  - http-custom-header-server-validation:sep-2243-server-no-xmcp-tool
-  - http-custom-header-server-validation:sep-2243-server-decode-base64
-  - http-custom-header-server-validation:sep-2243-server-validate-param-match
-  - http-custom-header-server-validation:sep-2243-server-reject-invalid-param-chars
-  - http-custom-header-server-validation:sep-2243-server-reject-param-mismatch
-
   # --- SEP-2322: the MRTR retry half -----------------------------------------
   # InputRequiredResult exists and tools/call can answer with one — that is what
   # makes server-stateless green. What is missing is the second round trip: the
@@ -49,7 +38,6 @@ server:
   # keyword), so the run summary counts them as passed — but the baseline
   # evaluator still wants them declared, and declaring them is right: each is a
   # SHOULD the SDK does not yet honour.
-  - http-header-validation:sep-2243-server-reject-error-code
   - input-required-result-ignore-extra-params:sep-2322-ignore-unexpected-params
   - input-required-result-missing-input-response:sep-2322-missing-response-rerequests
   - sep-2164-resource-not-found:sep-2164-data-uri

tests/Conformance/server-stateless.php

@@ -93,6 +93,21 @@ $protocol = Server::builder()
         name: 'test_logging_tool',
         description: 'Emits a server-side log message while returning normally',
     )
+    // Mirrors its arguments into Mcp-Param-* headers (SEP-2243), so the header/
+    // body agreement rules have something to be checked against.
+    ->addTool(
+        static fn (string $region = '', int $retries = 0): string => sprintf('region=%s retries=%d', $region, $retries),
+        name: 'test_custom_headers',
+        description: 'Tests custom header mirroring via x-mcp-header',
+        inputSchema: [
+            'type' => 'object',
+            'properties' => [
+                'region' => ['type' => 'string', 'x-mcp-header' => 'Region'],
+                'retries' => ['type' => 'integer', 'x-mcp-header' => 'Retries'],
+            ],
+            'required' => ['region'],
+        ],
+    )
     // Resources
     ->addResource(static fn () => 'This is the content of the static text resource.', 'test://static-text', 'static-text', 'A static text resource for testing')
     ->addResource(static fn () => fopen('data://image/png;base64,'.Elements::TEST_IMAGE_BASE64, 'r'), 'test://static-binary', 'static-binary', 'A static binary resource (image) for testing')

tests/Unit/Server/Stateless/StandardHeaderValidatorTest.php

@@ -0,0 +1,165 @@
+<?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\Server\Stateless;
+
+use Mcp\Server\Stateless\StandardHeaderValidator;
+use PHPUnit\Framework\Attributes\DataProvider;
+use PHPUnit\Framework\Attributes\TestDox;
+use PHPUnit\Framework\TestCase;
+
+class StandardHeaderValidatorTest extends TestCase
+{
+    private StandardHeaderValidator $validator;
+
+    protected function setUp(): void
+    {
+        // No registry: the Mcp-Param dimension needs tool definitions and is
+        // covered by the conformance fixture, which has real ones. Everything
+        // here is registry-independent.
+        $this->validator = new StandardHeaderValidator();
+    }
+
+    #[TestDox('a request whose headers agree with its body passes')]
+    public function testConsistentRequestPasses(): void
+    {
+        $this->assertNull($this->validator->validate(
+            'tools/call',
+            ['name' => 'do_thing', 'arguments' => []],
+            ['Mcp-Method' => 'tools/call', 'Mcp-Name' => 'do_thing'],
+        ));
+    }
+
+    #[TestDox('a missing Mcp-Method is rejected')]
+    public function testMissingMethodHeaderRejected(): void
+    {
+        $this->assertStringContainsString(
+            'Mcp-Method',
+            (string) $this->validator->validate('tools/list', null, []),
+        );
+    }
+
+    #[TestDox('an Mcp-Method that disagrees with the body is rejected')]
+    public function testMismatchedMethodHeaderRejected(): void
+    {
+        $this->assertStringContainsString(
+            'does not match',
+            (string) $this->validator->validate('tools/list', null, ['Mcp-Method' => 'prompts/list']),
+        );
+    }
+
+    #[TestDox('header names compare case-insensitively')]
+    #[DataProvider('headerCasings')]
+    public function testHeaderNameCasingIsIgnored(string $name): void
+    {
+        $this->assertNull($this->validator->validate('tools/list', null, [$name => 'tools/list']));
+    }
+
+    /**
+     * @return iterable<string, array{string}>
+     */
+    public static function headerCasings(): iterable
+    {
+        yield 'canonical' => ['Mcp-Method'];
+        yield 'lowercase' => ['mcp-method'];
+        yield 'uppercase' => ['MCP-METHOD'];
+        yield 'mixed' => ['mCp-MeThOd'];
+    }
+
+    #[TestDox('surrounding whitespace is not part of a header value (RFC 9110 §5.5)')]
+    public function testOptionalWhitespaceIsTrimmed(): void
+    {
+        $this->assertNull($this->validator->validate(
+            'tools/call',
+            ['name' => 'do_thing'],
+            ['Mcp-Method' => 'tools/call', 'Mcp-Name' => '   do_thing  '],
+        ));
+    }
+
+    #[TestDox('Mcp-Name is required when the body carries a name, and rejected when it disagrees')]
+    public function testNameHeaderMustMatchBody(): void
+    {
+        $body = ['name' => 'do_thing'];
+
+        $this->assertStringContainsString('Missing required Mcp-Name', (string) $this->validator->validate(
+            'tools/call',
+            $body,
+            ['Mcp-Method' => 'tools/call'],
+        ));
+
+        $this->assertStringContainsString('does not match', (string) $this->validator->validate(
+            'tools/call',
+            $body,
+            ['Mcp-Method' => 'tools/call', 'Mcp-Name' => 'something_else'],
+        ));
+    }
+
+    #[TestDox('a method that carries no name does not require the header')]
+    public function testNamelessMethodNeedsNoNameHeader(): void
+    {
+        $this->assertNull($this->validator->validate('tools/list', null, ['Mcp-Method' => 'tools/list']));
+    }
+
+    #[TestDox('each method names its subject through its own params member')]
+    #[DataProvider('nameSources')]
+    public function testNameIsReadFromTheRightMember(string $method, array $params, ?string $expected): void
+    {
+        $this->assertSame($expected, StandardHeaderValidator::nameFor($method, $params));
+    }
+
+    /**
+     * @return iterable<string, array{string, array<string, mixed>, ?string}>
+     */
+    public static function nameSources(): iterable
+    {
+        yield 'tools/call uses name' => ['tools/call', ['name' => 'a'], 'a'];
+        yield 'prompts/get uses name' => ['prompts/get', ['name' => 'b'], 'b'];
+        yield 'resources/read uses uri' => ['resources/read', ['uri' => 'test://c'], 'test://c'];
+        yield 'tasks/get uses taskId' => ['tasks/get', ['taskId' => 'd'], 'd'];
+        yield 'tools/list has no subject' => ['tools/list', [], null];
+        // A non-string value is not a name: treating it as one would compare a
+        // header against something that was never a header value.
+        yield 'non-string name is ignored' => ['tools/call', ['name' => 42], null];
+    }
+
+    #[TestDox('a plain header value decodes to itself')]
+    public function testPlainValuePassesThroughDecode(): void
+    {
+        $this->assertSame('Hello', StandardHeaderValidator::decode('Hello'));
+    }
+
+    #[TestDox('a well-formed Base64 wrapper decodes to its contents')]
+    public function testValidBase64Decodes(): void
+    {
+        $this->assertSame('Hello', StandardHeaderValidator::decode('=?base64?'.base64_encode('Hello').'?='));
+    }
+
+    #[TestDox('malformed Base64 is refused rather than salvaged')]
+    #[DataProvider('malformedBase64')]
+    public function testMalformedBase64IsRefused(string $encoded): void
+    {
+        // PHP's decoder will happily return bytes for most of these. Accepting
+        // them would let a corrupted header silently compare equal — or, worse,
+        // silently unequal — instead of being reported as the transport-level
+        // fault it is.
+        $this->assertNull(StandardHeaderValidator::decode('=?base64?'.$encoded.'?='));
+    }
+
+    /**
+     * @return iterable<string, array{string}>
+     */
+    public static function malformedBase64(): iterable
+    {
+        yield 'missing padding' => ['SGVsbG8'];
+        yield 'out-of-alphabet character' => ['SGVsbG8!'];
+        yield 'stray whitespace' => ['SGVs bG8='];
+    }
+}