Quick answer
MCP 2026-07-28 makes Streamable HTTP easier to govern at the gateway. POST requests expose method and target name through required Mcp-Method and Mcp-Name headers alongside protocol-version signaling. Header values mirror the JSON-RPC body; a mismatch produces HeaderMismatchError code -32020.
Cacheable list and read results require ttlMs and cacheScope. These are freshness and sharing controls, not permission grants.
Gateway control surface
| Field | Use | Safety check |
|---|---|---|
Mcp-Protocol-Version | Version routing and audit | Match the request metadata and supported version |
Mcp-Method | Method-aware policy | Match the JSON-RPC method |
Mcp-Name | Tool, prompt, or resource policy | Match the body target and avoid leaking sensitive names |
ttlMs | Client freshness hint | Bound stale-use risk and refresh behavior |
cacheScope | public or private sharing boundary | Never share tenant-specific data through a public cache |
Trace context in _meta | Propagate traceparent, tracestate, and baggage | Filter sensitive baggage and preserve trust boundaries |
The spec also recommends deterministic tools/list ordering to improve client caching and prompt-cache hit rates.
Implementation checklist
- Reject header/body mismatches before dispatch.
- Authorize on verified identity and resource scope, not on a client-controlled name alone.
- Rate-limit by tenant, method, name, and cost class.
- Set
cacheScope: "private"for user- or tenant-specific results. - Treat
ttlMsas a maximum freshness hint, not proof that the underlying source is unchanged. - Redact sensitive header and trace fields from logs and exports.
- Test proxies for casing, duplicate headers, oversize values, and downgrade behavior.
Use the server discovery guide for version selection and the stateless compatibility guide for rollout.
Frequently asked questions
Which headers are required?
The changelog requires Mcp-Method and Mcp-Name on Streamable HTTP POST requests and documents protocol-version signaling.
What is the mismatch error?
HeaderMismatchError, code -32020 in the 2026-07-28 revision.
Can public cache scope expose private data?
It can if assigned incorrectly. Determine scope from reviewed server policy, never from untrusted client input.
Official sources
Source check: August 6, 2026. Verify final transport schema, header requirements, cache semantics, and error codes.