Skip to content

feat: add strict stateless protocol metadata validation - #1091

Merged
DaleSeo merged 2 commits into
modelcontextprotocol:mainfrom
mrcs64:fix/reject-missing-request-protocol-metadata
Jul 30, 2026
Merged

feat: add strict stateless protocol metadata validation#1091
DaleSeo merged 2 commits into
modelcontextprotocol:mainfrom
mrcs64:fix/reject-missing-request-protocol-metadata

Conversation

@mrcs64

@mrcs64 mrcs64 commented Jul 30, 2026

Copy link
Copy Markdown
Contributor

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.

@github-actions github-actions Bot added T-test Testing related changes T-core Core library changes T-transport Transport layer changes labels Jul 30, 2026
@mrcs64
mrcs64 marked this pull request as ready for review July 30, 2026 08:19
@mrcs64
mrcs64 requested a review from a team as a code owner July 30, 2026 08:19
@github-actions github-actions Bot added the T-documentation Documentation improvements label Jul 30, 2026
DaleSeo
DaleSeo previously approved these changes Jul 30, 2026

@DaleSeo DaleSeo 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.

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

@DaleSeo
DaleSeo force-pushed the fix/reject-missing-request-protocol-metadata branch from eae071a to bc3f072 Compare July 30, 2026 19:51
@DaleSeo
DaleSeo merged commit 983a137 into modelcontextprotocol:main Jul 30, 2026
22 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

T-core Core library changes T-documentation Documentation improvements T-test Testing related changes T-transport Transport layer changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants