v2 remove console warns on middleware

[KKonstantinov]

Remove console.warn log pollution and add skipHostHeaderValidation option

Motivation and Context

Fixes #1515. The middleware packages (@modelcontextprotocol/express, @modelcontextprotocol/hono) emit a console.warn when binding to 0.0.0.0 or :: without allowedHosts. This pollutes server logs for users who intentionally bind to all interfaces (e.g., behind a reverse proxy in a container). Libraries should not produce unsolicited log output in environments they don't own.

Additionally, there was no way to opt out of the automatic localhost host-header validation — useful when running behind a reverse proxy that rewrites the Host header.

This PR:

1. Removes the console.warn entirely. The allowedHosts option is already well-documented in JSDoc.
2. Adds skipHostHeaderValidation — an explicit opt-out from all automatic host-header validation middleware.
3. Uses a discriminated union type (HostHeaderValidationOptions) so that allowedHosts and skipHostHeaderValidation: true are mutually exclusive at the type level — passing both is a compile error, not a silent precedence rule.

How Has This Been Tested?

• All existing tests updated and passing for both @modelcontextprotocol/express and @modelcontextprotocol/hono
• New tests added for skipHostHeaderValidation: true on both localhost and 0.0.0.0 hosts
• Hono tests verify at the HTTP level that validation middleware is actually skipped (requests with arbitrary Host headers succeed)
• Full build, typecheck, and lint pass across both packages

Breaking Changes

• The console.warn when binding to 0.0.0.0/:: without allowedHosts is removed. This is a behavior change but not a breaking API change — no user code depended on this warning.
• CreateMcpExpressAppOptions and CreateMcpHonoAppOptions changed from interface to type (intersection with HostHeaderValidationOptions). This is source-compatible for all usage patterns except extends/implements on the interface, which is unlikely for options objects.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The HostHeaderValidationOptions discriminated union type is defined independently in both packages (no shared import) to avoid coupling the middleware packages. The pattern is identical:

type HostHeaderValidationOptions =
    | { skipHostHeaderValidation: true; allowedHosts?: never }
    | { skipHostHeaderValidation?: false; allowedHosts?: string[] };

This ensures that allowedHosts is only accepted when validation is enabled, catching misconfiguration at compile time rather than silently ignoring one option.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9ee628f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@1776

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@1776

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@1776

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@1776

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@1776

commit: 9ee628f

[KKonstantinov]

@claude review

[claude]

The previously flagged integration test bug has been fixed. The implementation looks correct, but this PR adds a new option to bypass DNS rebinding protection, so a human should sign off on the API design.

Extended reasoning...

Overview

This PR modifies the Express and Hono middleware packages to (1) remove console.warn log pollution when binding to 0.0.0.0/:: without allowedHosts, and (2) add a new skipHostHeaderValidation option using a discriminated union type that makes allowedHosts and skipHostHeaderValidation: true mutually exclusive at the type level. Five files are changed across both middleware packages and integration tests.

Security risks

The core change introduces an explicit opt-in to disable DNS rebinding protection entirely via skipHostHeaderValidation: true. While the implementation is correct (requires explicit opt-in, default behavior unchanged, clean type constraints), this is a new security-relevant API surface. A human reviewer should validate that this escape hatch is appropriate and that the documentation/naming adequately communicates the security implications.

Level of scrutiny

This warrants careful human review. Although the code is well-structured and the discriminated union type prevents misconfiguration at compile time, the PR touches security middleware (host header validation / DNS rebinding protection). The interface-to-type change is also technically a minor breaking change for anyone extending the options interface. A missing changeset was also flagged by the changeset bot.

Other factors

The author addressed the integration test bug I previously flagged — the old console.warn assertion tests are now replaced with proper HTTP-level supertest assertions. The nit about Express unit tests only checking toBeDefined() is mitigated by the new integration tests which do verify HTTP behavior with supertest. Test coverage is now solid across both packages.