[Server] Let a framework integration opt out of the HTTP edge middleware without a warning

[mglaman]

StreamableHttpTransport logs a warning whenever it gets an empty middleware list (added in #307):

Streamable HTTP transport started with an empty middleware list. Default security protections (CORS, DNS rebinding, protocol version validation) are disabled. …

In the Drupal integration (mcp_server), the empty list is deliberate. Drupal's HTTP layer already handles both edge checks:

• CORS comes from Drupal's cors.config. CorsMiddleware would add a second set of CORS headers.
• Host validation comes from Drupal's trusted_host_patterns, which are regular expressions. DnsRebindingProtectionMiddleware takes an exact host list and answers 403 for any host not on it.

Since 0.8, the protocol version check runs through handshakeMiddleware() no matter what list is passed, so the "protocol version validation" part of the message no longer applies.

PHP builds a new transport for every request, so this warning becomes one log entry per MCP request on every Drupal site using the SDK.

Could the transport accept an explicit opt-out that doesn't warn? For example, a constructor flag, or a documented value that means "the host application handles CORS and Host validation". The warning still makes sense for an accidental [].

Downstream: https://git.drupalcode.org/project/mcp_server/-/work_items/3585939

[sveneld]

I would prefer not to introduce an additional flag for this.

Flags tend to make the transport configuration more complicated by adding another special case to the constructor semantics.

If an integration intentionally does not need any of the SDK edge middleware because those concerns are already handled by the host framework, it can make that intention explicit by passing a no-op middleware instead of an empty array.

For example:

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

$middleware = [
    new class implements MiddlewareInterface {
        public function process(
            ServerRequestInterface $request,
            RequestHandlerInterface $handler,
        ): ResponseInterface {
            return $handler->handle($request);
        }
    },
];

This avoids introducing another flag while keeping [] useful as a signal that may have been passed accidentally.

It also makes the opt-out explicit at the point where middleware is configured: there is intentionally a middleware stack, and its only middleware simply passes the request through.

[mglaman]

Thank you for the solution! What do you think about adding notes in the transport docblock or the HTTP transport docs about this, for other integrators

[charredlatte]

I think :

PHP` builds a new transport for every request, so this warning becomes one log entry per MCP request on every Drupal site using the SDK.

is a valid fix, but like sveneld said, it's adding extra steps that should not be handled in transport configuration.

IMO, adding notes in the transport docblock or the HTTP transport docs is the correct direction to go.

[chr-hertel]

Thanks for raising this - that middleware thing grew into a bit complicated mess while adopting the latest spec - maybe not the best fit, but the entire double protocol stuff is - uhm - not ideal, but luckily temporary.

I think this approach + docs and maybe adopting the log message is a pragmatic way. Open for moving that PassThroughMiddleware into the package, if that helps 👍

[mglaman]

@chr-hertel thank you for merging! Any idea when there may be a release containing this? Working to get the Drupal integration into a stable position for introduction to Drupal CMS and promotion. I wasn't sure the release cadence of the SDK

[chr-hertel]

Hopefully end of week

[mglaman]

Thank you @chr-hertel! I appreciate the team's work here