Compatibility¶
mcpdev speaks two first-class MCP wire eras: 2025-11-25 (stateful initialize / initialized) and 2026-07-28 (stateless per-request _meta). Both are required. The era matrix, negotiation rules, and fallback behavior are below.
What mcpdev supports¶
| Kind | Status | Notes |
|---|---|---|
MCP 2025-11-25 |
First-class | Handshake lifecycle, optional Mcp-Session-Id, session-scoped list-change notifications. |
MCP 2026-07-28 |
First-class | server/discover, _meta on every request, Streamable HTTP POST-only, subscriptions/listen. |
| stdio | Built-in | Standard transport in both eras. |
| Streamable HTTP | Built-in | Standard transport; era selects session/GET vs POST-only. |
HTTP+SSE (2024-11-05) |
Compatibility mode | Deprecated. Off unless explicitly enabled. |
| gRPC | Adapter only | Not an MCP-standard transport. No default CLI transport named grpc. Mapping is unspecified until a real protobuf service exists. |
Negotiation (do not treat every 400 as legacy)¶
HTTP. Try a 2026-07-28 request first. On HTTP 400, read the body. Modern errors (UnsupportedProtocolVersionError -32022, MissingRequiredClientCapabilityError -32021, HeaderMismatch -32020) mean a modern server: retry or fix the request. Fall back to initialize only when the body is empty or not a recognized modern JSON-RPC error.
stdio. Probe server/discover with per-request _meta (io.modelcontextprotocol/protocolVersion, clientInfo, clientCapabilities). A DiscoverResult or a recognized modern error stays in the stateless era. Any other error or a timeout may fall back to initialize.
Version policy. mcpdev prefers 2026-07-28. It walks that preference list and takes the first string also present in supportedVersions (or in UnsupportedProtocolVersionError.data.supported). It retries discover once with the selected version. No mutually supported modern version is a protocol error, not a silent initialize.
Session diagnostics record requested (the first version asked), discovered (supportedVersions when present), negotiated (protocolVersion after success), and fallback (true only when initialize was used after a legacy-shaped discover failure).
Sources: Streamable HTTP backward compatibility, stdio backward compatibility. Retrieved and re-checked 2026-09-19.
Legacy initialize diagnostics¶
A 2025-11-25 session is ready only after a successful initialize result and a following notifications/initialized notification. mcpdev records that path as handshake: initialize. Inventory commands can then read negotiated protocolVersion, serverInfo, instructions, and declared capabilities (tools, prompts, resources, and list-change/subscribe flags).
Older initialize-era dates the official Go SDK still speaks (2025-06-18, 2025-03-26) stay on the same stateful lifecycle. The session era remains 2025-11-25; protocolVersion keeps the dated string the server returned. HTTP+SSE (2024-11-05) is still off unless --allow-http-sse is set.
Handshake failures stay classified. They are never turned into an empty successful session.
| Failure | Typical class | What you see |
|---|---|---|
| Connect timeout or canceled handshake | Connection (10) |
Deadline or cancel; no session. |
| Server exit or closed pipe during initialize | Connection (10) |
Transport ended before a valid result. |
Unsupported protocolVersion |
Protocol (20) |
Dated version is not a supported initialize-era string. |
Malformed JSON or capabilities that is not an object |
Protocol (20) |
Decode failed; no session. |
Tool, prompt, or resource RPC before initialized |
Protocol (20) |
Stateful servers reject the call (-32600 on fixtures). |
RPC after Close |
Connection (10) |
Session is closed. |
--protocol 2025-11-25 sends initialize first. --protocol auto may probe server/discover and then fall back to initialize when the peer is a handshake server. notifications/initialized is sent only after a valid initialize result.
Incomplete results¶
Stopped pagination, a failed server/discover, an unsupported primitive, or an unused subscription MUST be reported as such. They are not empty successful catalogs.
Official references¶
Retrieved and re-checked 2026-09-19 (overview pages still distinguish stateful 2025-11-25 from stateless 2026-07-28; gRPC is not listed as a standard transport).