feat: Support MCP spec revision 2026-07-28

[aheritier]

Support MCP spec revision 2026-07-28

Summary

The Model Context Protocol has shipped 2026-07-28, now the latest protocol version and a major architectural refactor: MCP moves from stateful, session-based connections to a fully stateless, per-request model. The initialize/initialized handshake and Mcp-Session-Id header are gone; version and capabilities move to per-request _meta; servers advertise via a new mandatory server/discover RPC.

The second headline change is Multi Round-Trip Requests (MRTR): server-initiated blocking RPCs (sampling, elicitation, roots) are replaced by InputRequiredResult + client-side retry with inputResponses. Roots, Sampling, and Logging are deprecated (functional this revision); Tasks move to an opt-in extension; resource subscriptions are replaced by subscriptions/listen.

Go SDK status: ✅ v1.7.0 is out and fully supports 2026-07-28

github.com/modelcontextprotocol/go-sdk v1.7.0 was published 2026-07-28 with full protocol support. docker-agent is currently on v1.6.1 (negotiating 2025-03-26).

The SDK absorbs most of what initially looked like heavy lifting:

Area	Status
MRTR client re-architecture	✅ Handled transparently — SetSamplingHandler/SetElicitationHandler keep working via SDK middleware
subscriptions/listen migration	✅ SDK opens it automatically on Client.Connect when a list-changed handler is set
server/discover	✅ Implemented on both sides with automatic fallback to legacy initialize
Stateless handshake / version negotiation	✅ Automatic; negotiates highest mutually-supported version

What needs to change in docker-agent

1. Bump go.mod: v1.6.1 → v1.7.0
Compile breaks expected to be minor (types are largely additive; negotiation is automatic).

2. Set StreamableHTTPOptions.Stateless = true in pkg/mcp/server.go
Required to expose 2026-07-28 to HTTP clients. Without it, HTTP clients negotiate down to 2025-11-25. Stdio is unaffected.

3. Handle behavioral default changes
Two changes land unconditionally (with MCPGODEBUG escape hatches available until v1.9.0):

• ToolAnnotations.ReadOnlyHint/IdempotentHint are now always serialized (bare bool, no omitempty) — affects tool metadata output shape from serve mcp.
• JSON-RPC error codes updated across the board (UnsupportedProtocolVersion -32004 → -32022; non-2xx HTTP surfaces the JSON-RPC error body; etc.).

4. Update tests

• Replace "2025-03-26" fixture in pkg/tools/builtin/mcpcatalog/mcpcatalog_test.go
• Update e2e/sampling_test.go and e2e/mcp_test.go for new defaults

Key spec changes (for reference)

Core / protocol (breaking):

• Stateless model — sessions and Mcp-Session-Id removed; initialize/notifications/initialized/ping removed
• New mandatory server/discover RPC
• resultType required on all results ("complete" | "input_required" | …); missing value treated as "complete" for back-compat
• MRTR: InputRequiredResult + retry with inputResponses replaces server-initiated sampling/elicitation RPCs
• CacheableResult: tools/list etc. carry ttlMs + cacheScope; deterministic tool ordering recommended
• JSON-RPC error codes renumbered (-32020…-32099 reserved for spec)

Transport / auth:

• HTTP+SSE transport deprecated; SSE resumability (Last-Event-ID) removed — broken stream must re-issue request
• Streamable HTTP POST requires Mcp-Method/Mcp-Name headers
• OAuth: RFC 9207 iss validation now required; DCR (RFC 7591) deprecated in favor of Client ID Metadata Documents
• _meta carries W3C Trace Context (traceparent/tracestate/baggage)

Deprecations / relocations:

• Roots, Sampling, Logging deprecated (functional this revision)
• Tasks → io.modelcontextprotocol/tasks extension
• Resource subscribe/unsubscribe → subscriptions/listen

Official references

• Spec: https://modelcontextprotocol.io/specification/2026-07-28/
• Changelog: https://modelcontextprotocol.io/specification/2026-07-28/changelog
• GitHub repo: https://github.com/modelcontextprotocol/modelcontextprotocol
• TypeScript schema: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2026-07-28/schema.ts
• go-sdk v1.7.0 release: https://github.com/modelcontextprotocol/go-sdk/releases/tag/v1.7.0