Acknowledge notification POSTs with 202 on the 2026-07-28 HTTP entry
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/cancelledonsubscriptions/listenteardown, the Go client on context cancel and roots changes, and this SDK's deprecatedsend_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-Versionheader isn't a served modern version,-32022withsupported(the same answer a request gets) → otherwise202, 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 postednotifications/cancelledby client-chosen id would let one anonymous caller cancel another's work. - The split keys on presence of the
idmember (JSON-RPC 2.0 §4.1), not on which model happens to validate:JSONRPCNotificationignores 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-Methodvalidation on notifications: the revision leaves header requirements for notification POSTs undefined, and requiring them would reject the TypeScript client's listen-teardown shape (noMcp-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;
-32022on an unserved version header;-32600across eight non-request/non-notification shapes includingid: null. - Interaction: driven through the mounted session manager under json/SSE ×
stateless_httpon/off; new catalog entryhosting:http:modern:notification-post-202supersedes the era-unboundedhosting:http:notifications-202at 2026-07-28. - Manually against a uvicorn-served
MCPServerin 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=Truemode the modern entry awaits the handler inline with nohttp.disconnectwatcher, so closing the stream — the revision's cancellation signal — doesn't cancel anything in that mode. Separate issue.