Acknowledge notification POSTs with 202 on the 2026-07-28 HTTP entry

Merged
MA
3mo ago
+254-37

The 2026-07-28 streamable-HTTP entry now answers a POST whose body is a single JSON-RPC notification with 202 Accepted (no body) and drops it, instead of 400 / -32600 "Body must be a single JSON-RPC request object".

Fixes #3324.

Motivation and Context

handle_modern_request validated every body as a JSONRPCRequest, so anything without an id — i.e. every notification — took the INVALID_REQUEST arm. That was a deliberate choice of the "cannot accept" branch of streamable-http §Sending Messages item 5, on the grounds that the revision defines no client-to-server notifications over HTTP, with an in-code TODO recording accept-vs-refuse as an open call.

#3324 supplies what that TODO was waiting for: production clients do POST notifications/cancelled at 2026-07-28, and the result is a steady stream of 400s that makes 4xx useless as a failure signal. Looking around:

  • Both branches are conformant, but the surrounding spec text leans accept: item 4 names notifications as a valid POST body, the message-flow diagram shows Notification → 202, transports §Messages says a binding MUST deliver client-sent notifications, and cancellation §Error Handling asks servers to ignore stray cancellation notifications rather than error. Nothing forbids a client from sending one.
  • The TypeScript server 202s any notification on the modern path (pinned for exactly this shape); C# and rmcp 202 as well. Our own legacy leg 202s the same POST.
  • Real senders exist beyond the reporter's: the TypeScript client POSTs notifications/cancelled on subscriptions/listen teardown, the Go client on context cancel and roots changes, and this SDK's deprecated send_roots_list_changed() / send_progress_notification(). The Go client treats an id-less 4xx on a notification as fatal to the session, so the 400 was worse than noise there.

What changes

  • An id-less single-object body goes to a notification arm: shape-validate → if the MCP-Protocol-Version header isn't a served modern version, -32022 with supported (the same answer a request gets) → otherwise 202, empty body, debug log, not dispatched. There is nothing for a notification to act on in a per-request exchange (cancel by closing the response stream), and honouring a posted notifications/cancelled by client-chosen id would let one anonymous caller cancel another's work.
  • The split keys on presence of the id member (JSON-RPC 2.0 §4.1), not on which model happens to validate: JSONRPCNotification ignores unknown keys, so {"id": null, "method": ...} would otherwise be mistaken for a notification and silently 202'd when it is owed an error.
  • Posted responses, batches, scalars and malformed-id requests stay 400 -32600; the message now reads "…request or notification object".
  • No _meta / Mcp-Method validation on notifications: the revision leaves header requirements for notification POSTs undefined, and requiring them would reject the TypeScript client's listen-teardown shape (no Mcp-Method).

Deliberately not done: dispatching accepted notifications to registered Server notification handlers (the modern stdio path does). For spec methods it's moot at 2026-07-28; for custom methods it's an additive follow-up if wanted.

How Has This Been Tested?

  • Unit: the old 400 pin is replaced with 202 across four notification shapes (bare, removed-at-2026 method, custom, enveloped) asserting a registered handler never runs; -32022 on an unserved version header; -32600 across eight non-request/non-notification shapes including id: null.
  • Interaction: driven through the mounted session manager under json/SSE × stateless_http on/off; new catalog entry hosting:http:modern:notification-post-202 supersedes the era-unbounded hosting:http:notifications-202 at 2026-07-28.
  • Manually against a uvicorn-served MCPServer in all three configurations with the reporter's exact request, the enveloped shape, and the rejection cases; a 202 followed by a request on the same keep-alive connection is served normally.

Breaking Changes

Observable wire change on the 2026-07-28 HTTP entry only: a notification POST that previously got 400 -32600 now gets 202. It relaxes rather than tightens, and matches the legacy leg and the other SDKs. The -32600 message text for the remaining rejections changed wording.

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

  • #3192 does not touch _streamable_http_modern.py, so this doesn't interact with it.
  • No conformance scenario covers a notification POST on the 2026-07-28 wire either way; worth adding under modelcontextprotocol/conformance#266.
  • Adjacent, not addressed here: in json_response=True mode the modern entry awaits the handler inline with no http.disconnect watcher, so closing the stream — the revision's cancellation signal — doesn't cancel anything in that mode. Separate issue.