Skip to content

ADR-045: MCP 2026-07-28 Specification Adoption (Tasks, Server Card, Stateless Transport)

Status: Implemented 2026-07-03 (P1 MCP wiring blocked-pending-SDK v2 — #425) Date: 2026-07-03 Decision Makers: Chris Joseph, LLM Council Council Review: 2026-07-03 (4 models, balanced) — feedback incorporated: task authz, task-state persistence/expiry, phase independence, rollback semantics Related: ADR-012 (MCP reliability — this extends it), ADR-040 (timeouts), ADR-046 (streaming — complementary)

Context

The council's #1 documented MCP UX pain is client transport timeouts: high (~180s) and reasoning (~600s) tiers exceed typical MCP client defaults (~60s), forcing users to raise MCP_TIMEOUT manually (documented in the README and the consult_council tool description). A long deliberation that outlives its transport is lost.

The MCP 2026-07-28 specification (release candidate published; final on 2026-07-28) ships primitives that address this directly:

  • Tasks — a first-class long-running-operation primitive: create a task, poll/resume it, retrieve results after client disconnects. Purpose-built for 30–600s deliberations.
  • Server Cards — structured server metadata at a .well-known URL so registries (19k+ indexed servers) and clients can discover capabilities without connecting.
  • Stateless Streamable HTTP — protocol-level statelessness so servers run behind load balancers with scalable session handling.

Decision

Adopt the 2026-07-28 spec in three opt-in, backward-compatible phases. Older clients keep today's synchronous tools unchanged.

Phase 1 — Tasks-backed deliberation

  • Expose council deliberation and verification as MCP Tasks when the connected client advertises task support (feature-detect via the negotiated protocol version/capabilities): consult_council / verify create a task, emit progress, and deliver the result durably; clients may disconnect and resume.
  • Synchronous tool behaviour is preserved verbatim for clients without task support — no breaking change, no flag needed on the server side.
  • SDK dependency: bump the mcp Python SDK to the first release with 2026-07-28 support; if task lifecycle gaps remain (retry semantics/expiry are known open items in the RC), constrain to the stable subset and document.
  • Task state & persistence (council feedback): task results are stored in a bounded on-disk store under .council/tasks/ (same durability class as transcripts), keyed by an unguessable task id; default expiry 24h with size-capped eviction; in-memory fallback when the store is unavailable (degrades to sync semantics, never crashes).
  • Authorization (council feedback): the task id is a capability — 128-bit random, returned only to the creating client; retrieval requires it. Where the HTTP surface exposes tasks, LLM_COUNCIL_API_TOKEN (ADR-038) gates access exactly as for synchronous endpoints. No cross-client enumeration (no task listing without auth).
  • Rollback (council feedback): the synchronous path IS the rollback — task exposure is capability-negotiated per client and additionally kill-switched by LLM_COUNCIL_MCP_TASKS=false.

Phases 2 and 3 are independent of Phase 1 and of each other (council feedback): any subset may ship alone.

Phase 2 — Server Card

  • Serve a Server Card at .well-known from the HTTP server, and ship a static card in the repo for registry submission: name, capabilities (tools, tiers), auth expectations, and docs links.
  • Card content generated from the actual tool registry (no drift).

Phase 3 — Stateless transport alignment

  • Audit session state in the MCP server path; move any per-session state into request scope or durable stores (task results) so multiple instances behind a load balancer behave correctly. Validate with a two-instance smoke test.

Consequences

Positive: kills the MCP_TIMEOUT footgun for long tiers; registry discoverability; horizontal scalability; early, correct adoption of a spec finalizing within weeks is high-visibility for the project.

Negative / risks: SDK availability/decay of experimental Task semantics (mitigation: feature-detect + sync fallback, pin SDK, constrain to stable subset); Server Card schema may shift between RC and final (mitigation: ship after the 2026-07-28 final, generate from code).

Definition of Done (per phase)

Code + tests (incl. old-client fallback proving byte-identical sync behaviour); user docs (README MCP section — retire the MCP_TIMEOUT warning for task-capable clients — CLAUDE.md, CHANGELOG); LLM-facing tool descriptions updated for task flows.

References

  • MCP 2026 roadmap & 2026-07-28 RC (modelcontextprotocol.io / blog)
  • docs/roadmap-2026-h2.md item 2 (sources)