feat: add strict stateless protocol metadata validation

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.

[mrcs64]

Add an opt-in Streamable HTTP server setting that requires stateless JSON-RPC
request POSTs to carry their per-request protocol signals before handler
dispatch.

Motivation and Context

The general-purpose SDK preserves compatibility when
MCP-Protocol-Version is absent by treating a stateless request as protocol
version 2025-03-26. Modern-only servers need a supported way to reject that
fallback without changing the SDK default or maintaining custom middleware.

StreamableHttpServerConfig::with_stateless_protocol_metadata_required(true)
adds that enforcement on requests routed statelessly:

• non-initialize requests missing MCP-Protocol-Version return HTTP 400 with
  HeaderMismatch (-32020) before dispatch
• ordinary requests with the header but without
  _meta.io.modelcontextprotocol/protocolVersion return HTTP 400 with
  Invalid Params (-32602) before dispatch
• initialize, discovery, notifications, and legacy session routing retain
  their existing behavior and error precedence

The validator checks metadata presence rather than applying a version
allowlist. In practice, rmcp clients negotiated below 2026-07-28 do not
attach per-request protocol metadata, so enabling this setting rejects their
ordinary requests. Servers using it should normally restrict
ServerHandler::supported_protocol_versions() to 2026-07-28 and later.

This complements #1089. That PR validates required body metadata when a
request already selects 2026-07-28; this opt-in setting additionally lets a
strict stateless server reject requests that omit both version signals and
would otherwise take the compatibility fallback.

How Has This Been Tested?

Added invocation-counter integration tests covering:

• the disabled-by-default compatibility path
• missing header and missing body metadata rejection before dispatch
• successful dispatch when both signals are present
• rejection of the request shape emitted by pre-2026-07-28 rmcp clients
• standard-header validation precedence
• initialize, discovery, and notification behavior
• mixed routing with a valid legacy session
• required 404 responses for unknown and terminated legacy sessions

The focused Streamable HTTP protocol-version suite passes 18 tests.

Also ran:

cargo clippy -p rmcp --all-features --all-targets -- -D warnings
cargo doc -p rmcp --all-features --no-deps
cargo fmt --all -- --check

Breaking Changes

None. The new setting defaults to false, and the legacy session path is
unchanged.

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 setting is enforced only after routing selects the stateless branch. Set
legacy_session_mode(false) when every request must use that path. With mixed
routing enabled, regression coverage verifies that the setting does not shadow
legacy session dispatch or the required 404 response for unknown and
terminated sessions.

[DaleSeo]

Makes sense! I'll merge this after #1089 to avoid conflicts.