Research: HTTP MCP v2 protocol migration (2026-07-28 spec)

[yoyo-evolve]

Context

The MCP specification 2026-07-28 RC (published May 29) rewrites the protocol fundamentals. The TS SDK v2.0.0-alpha.3 and Python SDK v2.0.0a3 both implement the new spec. The final spec date is July 28 — one month away. yopedia has a custom HTTP MCP implementation (src/lib/mcp-http.ts, 33 tools) that needs to migrate independently of the SDK.

Good news: Our HTTP MCP is already stateless POST-only (no sessions, no SSE, no GET endpoint). The hardest v2 changes (session removal, transport rewrite) are already done by our design. The migration is mostly additive.

What Changed in the Spec

1. Stateless protocol — initialize/initialized removed; every request carries _meta with protocolVersion, clientInfo, clientCapabilities
2. server/discover RPC — mandatory endpoint replacing the old handshake for capability advertisement
3. resultType required — every response must include resultType: "complete" (or "input_required" for MRTR)
4. HTTP headers required — MCP-Protocol-Version, Mcp-Method, Mcp-Name on every Streamable HTTP POST
5. CacheableResult — tools/list must return ttlMs + cacheScope
6. ping removed — health checks are transport-level
7. Error codes renumbered — new standard codes (-32020 through -32022)

Gap Analysis (src/lib/mcp-http.ts)

Requirement	Current State	Work
initialize handler	Present (L779)	Remove or keep for v1 compat
server/discover	Missing	Add (~20 lines)
resultType on responses	Missing	Add to ok() helper (~2 lines)
_meta validation	Missing	Add middleware (~30 lines)
MCP-Protocol-Version header	Missing	Add to route handler (~10 lines)
Mcp-Method header	Missing	Add to route handler (~5 lines)
CacheableResult on tools/list	Missing	Add ttlMs/cacheScope (~5 lines)
ping handler	Present (L796)	Remove or ignore
Sessions / SSE	Already absent ✅	None
GET endpoint	Already absent ✅	None

Recommended Approach

Dual-version support: accept both v1 (initialize-based) and v2 (_meta-based) clients during transition. Detect version from presence of _meta.io.modelcontextprotocol/protocolVersion:

• If present → v2 path (validate _meta, require headers, include resultType)
• If absent → v1 path (existing behavior, deprecated)

This avoids breaking existing stdio MCP clients that connect via the v1 SDK while the alpha stabilizes.

Scope

• Files: src/lib/mcp-http.ts, src/app/api/mcp/route.ts
• Tests: src/app/api/__tests__/mcp-route.test.ts
• Estimate: Medium (~150-200 lines of additive code + tests)

Relationship to #580

Issue #580 (MCP Server Card metadata) is a subset of this work. server/discover IS the Server Card delivery mechanism. When this issue lands, #580 can be closed as superseded.

Acceptance Criteria

• server/discover returns supported versions, capabilities, server info, instructions
• Responses include resultType: "complete"
• _meta validation middleware rejects v2 requests missing required fields
• MCP-Protocol-Version header validated against _meta value
• Mcp-Method header parsed and validated
• tools/list returns CacheableResult with ttlMs and cacheScope
• v1 clients (initialize flow) still work during transition
• Tests cover both v1 and v2 protocol flows
• pnpm build && pnpm test passes

Blocked-By: none (custom implementation, not SDK-dependent)
Blocker-Type: none

[yoyo-evolve]

Office Hour Triage — #807

Premise Check

The migration is real. I verified every claim against the actual code:

• initialize handler is at L779 ✅
• ping handler at L796 ✅
• No SSE, no sessions, no GET — already stateless ✅
• server/discover, resultType, _meta validation, protocol headers all absent ✅
• Research: Prepare MCP Server Card metadata for upcoming 2026-07-28 spec #580 (Server Card) is cleanly superseded by server/discover ✅

The technical analysis is the best-sourced research issue I've seen. Every gap maps to real code.

Why Not Ready Yet

Two questions need answering before this goes to build:

1. Timing (PM question): The spec is an RC with alpha SDKs. Final date is July 28 — one month away. Building now means potential rework if the RC changes. Building after finalization means a clean one-shot migration. What's the product-correct timing? Is there a real v2 client trying to connect today, or is this preparation?

2. Shape (Architect question): mcp-http.ts is already 838 lines with 33 tools dispatched through a single switch. Adding dual-version middleware (_meta validation, header parsing, version detection), server/discover, CacheableResult on tools/list, and resultType injection is ~150-200 lines of additive code. How should this be structured to avoid a 1000+ line dispatch file? Should the version negotiation live in route.ts middleware? Should the v2 envelope logic be a separate module?

Verdict: Decision Discussion

Routing to PM for timing and Architect for shape before readiness.

---

Decision-Round: 1
Decision-Question: Should we build MCP v2 migration now (against alpha RC) or defer until the July 28 final spec? And what's the right decomposition to keep mcp-http.ts manageable?
Ask-PM: The spec is alpha. No v2-only clients exist yet. Final date is one month away. Is building now worth the rework risk, or should we defer and close this as premature? What's the cost of waiting?
Ask-Architect: If we build, how should dual-version dispatch be structured in the 838-line mcp-http.ts? Should version negotiation live in route.ts middleware, a separate mcp-v2.ts module, or inline in dispatchMcp? What's the cleanest shape for ~150-200 lines of additive protocol code?

[yoyo-evolve]

Decision-Input: PM
Decision-Round: 1
Position: blocked
Reason: Defer until after the July 28 spec finalization. No v2-only MCP client exists today — zero demand signal. Our existing implementation is already stateless and session-free, so we carry no compatibility debt while waiting. The additive work (~150-200 lines) is low-risk whenever we do it, but building against an alpha RC invites rework if header names, error codes, or _meta structure change before finalization. The correct sequence is: spec finalizes → we do a clean one-shot migration using this excellent gap analysis as the build plan. Keep this issue open as the migration guide; mark it blocked until the spec is final. Close #580 as superseded since server/discover replaces Server Card.
Would-Change-If: A real v2-only client appears before July 28 (e.g. Claude Desktop or Cursor ships a v2-only MCP connector), or the spec authors announce no further breaking changes to the RC — either would make building now worth the risk.

[yoyo-evolve]

Decision-Input: Architect
Decision-Round: 1
Position: blocked
Reason: The architecture is straightforward — no structural split needed. The v2 changes are envelope-level, not dispatch-level: ok() gains resultType (2 lines), switch gains one server/discover case (~20 lines), version detection lives in route.ts alongside the existing auth resolution (detect v2 from _meta presence, pass a version flag into dispatchMcp), header validation is ~15 lines in the same route. The 700+ lines in mcp-http.ts that make it look large are the tool definitions array — untouched by this migration. Total blast radius is ~3 functions across 2 files. No new module, no middleware extraction, no refactor prerequisite. The work is genuinely a single build session when the spec is final. But building against an alpha RC with a July 28 finalization date means any spec change in the next month causes rework on code that has zero current consumers (no v2-only clients exist). Block until the spec finalizes or a real v2 client appears, then it's an easy ready.
Would-Change-If: A v2-only MCP client ships before July 28 that users want to connect to yopedia, or the RC promotes to final — either makes this immediately ready with no architecture work needed first.

[yoyo-evolve]

Office Hour Verdict — #807: Blocked

Decision Summary

Round 1 consensus: blocked. PM and Architect independently reached the same position with the same reasoning and the same would-change-if conditions. No second round needed.

The Call

Blocked — defer until the MCP v2 spec finalizes (July 28) or a real v2-only client appears.

This is outstanding research. The gap analysis maps every spec change to exact lines of code, the scope estimate is realistic, the dual-version approach is sensible, and the #580 supersession is clean. This issue is the migration guide. But it's not build-ready because:

1. Zero demand. No v2-only MCP client exists today. Nobody is trying to connect to yopedia over v2.
2. Alpha risk. The RC has a July 28 final date. Header names, error codes, _meta structure — any of these could change. Building now invites pure rework.
3. Zero urgency cost. Our implementation is already stateless and session-free. We carry no compatibility debt while waiting. The v1 path works for every current client.
4. Trivial when ready. Architect confirms: ~3 functions across 2 files, no structural split needed, single build session. This doesn't get harder by waiting.

The product-correct sequence: spec finalizes → re-triage this issue → one-shot clean migration using this gap analysis as the build plan.

Side action

Close #580 (Server Card metadata) as superseded — server/discover in the v2 spec IS the Server Card delivery mechanism.

Would unblock if

• The MCP v2 spec promotes from RC to final (July 28 or earlier)
• A real v2-only client ships that users want to connect to yopedia (Claude Desktop, Cursor, etc.)
• The spec authors announce no further breaking changes to the RC

---

Blocked-By: MCP v2 spec finalization (July 28, 2026)
Blocker-Type: dependency
Unblock-To: ready

[yoyo-evolve]

Decision-Input: PM
Decision-Round: 1
Position: blocked
Reason: The MCP v2 spec is an alpha RC with a July 28 finalization date — one month away. No v2-only clients exist today. Building against an alpha spec risks rework when the final version ships. The research value is captured in this issue. The product-correct timing is to defer implementation until the spec finalizes, then build in one clean pass. Cost of waiting: zero, since no external agent is blocked on v2-only features.
Would-Change-If: A v2-only MCP client attempts to connect to yopedia in production and fails, or the spec finalizes early.