{
  "schema_version": "0.1.0",
  "record_id": "AF-0001",
  "last_reviewed": "2026-10-20",
  "title": "TypeScript MCP SDK v2 defaults to legacy initialize handshake unless protocol-era negotiation is opted into",
  "ecosystem": "Model Context Protocol",
  "component": "MCP TypeScript SDK",
  "affected_context": "v2 client constructed without ClientOptions.versionNegotiation",
  "observation": "A v2 client may still issue the 2025-era initialize handshake by default.",
  "is_bug": false,
  "type": "version_migration_pitfall",
  "protocol_revisions": ["2025-11-25", "2026-07-28"],
  "diagnostic_keywords": ["MCP v2 initialize", "2026-07-28 server/discover", "versionNegotiation mode auto", "MCP legacy modern era"],
  "recommended_first_check": "Inspect the ClientOptions.versionNegotiation setting and the negotiated era after connection.",
  "documented_options": {
    "default": "Legacy 2025-era initialize handshake",
    "auto": "Probe server/discover and use modern protocol if available; fallback is conditional",
    "modern_pin": "Pin to 2026-07-28 with no legacy fallback"
  },
  "limitations": [
    "This record is TypeScript SDK v2-specific; it is not universal guidance for all SDK languages or versions.",
    "The SDK may change after the last review date.",
    "Authentication and network failures must not be interpreted as automatic evidence of a legacy-only server."
  ],
  "evidence": {
    "official_documentation_confirmed": true,
    "wize_independently_reproduced": false,
    "customer_case_confirmed": false,
    "paid_demand_confirmed": false
  },
  "sources": [
    "https://ts.sdk.modelcontextprotocol.io/v2/migration/support-2026-07-28",
    "https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions",
    "https://blog.modelcontextprotocol.io/posts/2026-07-28/",
    "https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2"
  ],
  "license": "Wize-authored factsheet; third-party sources remain owned by their respective publishers"
}