{"record":{"id":"db62f053cf1bb9e0","repo":"Hmbown/CodeWhale","slug":"mcp-server-unsupported-protocol-version-expected","errorCode":null,"errorMessage":"MCP server '{}': unsupported protocol version '{}' (expected {})","messagePattern":"MCP server '(.+?)': unsupported protocol version '(.+?)' \\(expected (.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/mcp/src/stdio_client.rs","lineNumber":440,"sourceCode":"    tools: bool,\n    resources: bool,\n}\n\nfn validate_initialize_result(\n    server_name: &str,\n    result: &Value,\n) -> Result<Option<ServerCapabilities>> {\n    let response = result.as_object().with_context(|| {\n        format!(\"MCP server '{server_name}': initialize result must be an object\")\n    })?;\n    let protocol_version = response\n        .get(\"protocolVersion\")\n        .and_then(Value::as_str)\n        .with_context(|| {\n            format!(\"MCP server '{server_name}': initialize result omitted protocolVersion\")\n        })?;\n    if protocol_version != PROTOCOL_VERSION {\n        bail!(\n            \"MCP server '{server_name}': unsupported protocol version '{protocol_version}' (expected {PROTOCOL_VERSION})\"\n        );\n    }\n\n    let server_info = response\n        .get(\"serverInfo\")\n        .and_then(Value::as_object)\n        .with_context(|| {\n            format!(\"MCP server '{server_name}': initialize result omitted serverInfo\")\n        })?;\n    for field in [\"name\", \"version\"] {\n        if !server_info.get(field).is_some_and(Value::is_string) {\n            bail!(\"MCP server '{server_name}': initialize serverInfo.{field} must be a string\");\n        }\n    }\n\n    match response.get(\"capabilities\") {\n        None => Ok(None),","sourceCodeStart":422,"sourceCodeEnd":458,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/433685b2024e7bc4c99e1e2e326bcad39b4d9d65/crates/mcp/src/stdio_client.rs#L422-L458","documentation":"During the MCP stdio handshake, `validate_initialize_result` compares the server's `initialize` response `protocolVersion` against the client's `PROTOCOL_VERSION` and bails on any mismatch. The client speaks exactly one protocol version and refuses to interoperate with a server that negotiated a different one, since message schemas may diverge. This prevents subtle incompatibilities from surfacing later as malformed responses.","triggerScenarios":"`spawn_with_timeouts` starts a server subprocess, sends the `initialize` request, and the JSON response's `protocolVersion` field is a string not equal to `PROTOCOL_VERSION`. (A missing/empty protocolVersion produces a different context error.)","commonSituations":"The installed MCP server binary is older or newer than the protocol version the client pins (e.g. after a client upgrade the server lags behind, or a stale cached binary); a wrapper script proxies and rewrites the response; a custom server hardcodes an old protocol version string like \"2024-10-07\".","solutions":["Upgrade (or downgrade) the MCP server binary so its protocol version matches the client's expected version.","Check which version the client expects and, if a newer server is intentionally ahead, update this library to the release supporting that protocol version.","Print the server's reported protocolVersion (`initialize` response) to confirm the exact mismatch before changing binaries.","If a proxy/wrapper sits between client and server, ensure it passes `protocolVersion` through unmodified."],"exampleFix":"// server package.json — pinned to an old protocol\n\"mcp-server\": { \"protocolVersion\": \"2024-10-07\" }\n// after: match the client's expected PROTOCOL_VERSION\n\"mcp-server\": { \"protocolVersion\": \"2025-03-26\" }","handlingStrategy":"validation","validationCode":"// before spawning, pin and document the server version\nif !supported_server_versions().contains(&config.server_version.as_str()) {\n    return Err(format!(\"server {} predates/passes pinned protocol version\", config.name));\n}","typeGuard":null,"tryCatchPattern":"match spawn_with_timeouts(&config, hs, req).await {\n    Err(e) if e.to_string().contains(\"unsupported protocol version\") => {\n        eprintln!(\"upgrade or downgrade the MCP server binary to match the client protocol\");\n    }\n    other => other,\n}","preventionTips":["Pin the MCP server binary version alongside the client and upgrade them together.","Log the server's reported protocolVersion on mismatch for fast triage.","Test handshakes in CI against the exact server versions you ship."],"tags":["mcp","protocol-version","handshake","version-mismatch"],"backgroundTag":"unsupported-operation","analyzedSha":"433685b2024e7bc4c99e1e2e326bcad39b4d9d65","analyzedAt":"2026-09-15T12:24:24.634Z","contentChangedAt":"2026-09-15T12:24:24.634Z","schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}