Skip to content

[Server] Add PassthroughMiddleware for the HTTP transport opt-out - #526

Merged
chr-hertel merged 2 commits into
modelcontextprotocol:mainfrom
mglaman:docs/middleware-pass-through-opt-out
Oct 6, 2026
Merged

chr-hertel merged 2 commits into
modelcontextprotocol:mainfrom
mglaman:docs/middleware-pass-through-opt-out

Conversation

@mglaman

@mglaman mglaman commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Closes #523

StreamableHttpTransport logs a warning on every request when it gets middleware: []. The constructor docblock and docs/run/http.md still describe [] as the way to drop the defaults, and the guide recommends it when the host application already handles CORS and host validation.

This PR ships the opt-out suggested in #523 as PassthroughMiddleware, a middleware that only calls $handler->handle($request):

$transport = new StreamableHttpTransport(
    $request,
    middleware: [new PassthroughMiddleware()],
);
  • PassthroughMiddleware in Mcp\Server\Transport\Http\Middleware.
  • The empty-list warning names it as the opt-out. It also no longer lists "protocol version validation" as disabled: since 0.8 the transport applies handshakeMiddleware() to handshake-era requests regardless of the custom list.
  • StreamableHttpTransport::__construct(): the docblock says an empty list logs a warning and points to PassthroughMiddleware.
  • docs/run/http.md: the middleware parameter links to a new "Opting Out of All Middleware" section. The "run only your own chain" example passed a non-empty list but told readers to pass [], so I reworded it.

StatelessHttpTransport doesn't warn on an empty list, so it's unchanged.

Tests: testPassthroughMiddlewareDisablesDefaultsWithoutWarning checks that the pass-through logs no warning and that CORS and DNS rebinding are off. The existing empty-list test still matches the new warning text.

Checked locally: transport unit tests pass, php-cs-fixer is clean, phpstan reports only the two existing ElicitationSchema.php errors from main, and zensical build --strict passed on the first commit.

🤖 Generated with Claude Code

Comment thread docs/run/http.md Outdated
@chr-hertel

Copy link
Copy Markdown
Member

Two things we could still do to improve this:

  • ship the PassthroughMiddleware
  • improve the log message

@chr-hertel chr-hertel added Server Issues & PRs related to the Server component enhancement Request for a new feature that's not currently supported labels Oct 5, 2026
@mglaman mglaman changed the title [Server] Document the pass-through opt-out for HTTP transport middleware [Server] Add PassthroughMiddleware for the HTTP transport opt-out Oct 6, 2026
@mglaman

mglaman commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor Author

Done in 279e78b: shipped PassthroughMiddleware with your spelling, and the warning now points to it.

@mglaman
mglaman force-pushed the docs/middleware-pass-through-opt-out branch from 7bf7b15 to 279e78b Compare October 6, 2026 16:43
StreamableHttpTransport logs a warning on every request when it gets an
empty middleware list, but the constructor docblock and the HTTP guide
still describe `[]` as the way to drop the defaults. Point integrators
that already handle CORS and host validation at a pass-through
middleware instead.

🤖 Assisted with AI
The docs no longer ask every host to write the same three-line class.
The empty-list warning now names it, and drops "protocol version
validation", which the transport applies to handshake-era requests
regardless of the custom list.

🤖 Assisted with AI
@chr-hertel
chr-hertel force-pushed the docs/middleware-pass-through-opt-out branch from 279e78b to 9878930 Compare October 6, 2026 22:42

@chr-hertel chr-hertel left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @mglaman!

@chr-hertel
chr-hertel merged commit 672586a into modelcontextprotocol:main Oct 6, 2026
27 checks passed
@mglaman
mglaman deleted the docs/middleware-pass-through-opt-out branch October 6, 2026 23:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement Request for a new feature that's not currently supported Server Issues & PRs related to the Server component

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants