{"record":{"id":"059f6ec9432d8c9a","repo":"googleapis/mcp-toolbox","slug":"unsupported-protocol-version","errorCode":"UNSUPPORTED_PROTOCOL_VERSION","errorMessage":"unsupported protocol version","messagePattern":"unsupported protocol version","errorType":"http","errorClass":"jsonrpc.Error","httpStatus":null,"severity":"error","filePath":"internal/server/mcp/jsonrpc/jsonrpc.go","lineNumber":163,"sourceCode":"\tId      RequestId      `json:\"id,omitempty\"`\n\tParams  *RequestParams `json:\"params,omitempty\"`\n}\n\n// NewError is the standard JSONRPC response sent back when an error has been encountered.\nfunc NewError(id RequestId, code int, message string, data any) JSONRPCError {\n\treturn JSONRPCError{\n\t\tJsonrpc: JSONRPC_VERSION,\n\t\tId:      id,\n\t\tError: Error{\n\t\t\tCode:    code,\n\t\t\tMessage: message,\n\t\t\tData:    data,\n\t\t},\n\t}\n}\n\nfunc NewUnsupportedProtocolVersionError(id RequestId, v string, enableDraft bool) (JSONRPCError, error) {\n\terr := fmt.Errorf(\"unsupported protocol version\")\n\treturn JSONRPCError{\n\t\tJsonrpc: JSONRPC_VERSION,\n\t\tId:      id,\n\t\tError: Error{\n\t\t\tCode:    UNSUPPORTED_PROTOCOL_VERSION,\n\t\t\tMessage: err.Error(),\n\t\t\tData: struct {\n\t\t\t\tSupported []string `json:\"supported\"`\n\t\t\t\tRequested string   `json:\"requested\"`\n\t\t\t}{\n\t\t\t\tSupported: mcputil.GetSupportedVersions(enableDraft),\n\t\t\t\tRequested: v,\n\t\t\t},\n\t\t},\n\t}, err\n}\n\nfunc NewHeaderMismatchedError(id RequestId, err error) JSONRPCError {","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/server/mcp/jsonrpc/jsonrpc.go#L145-L181","documentation":"NewUnsupportedProtocolVersionError builds a JSONRPCError when a client requests an MCP protocol version the server does not support, during version negotiation in the initialize handshake. The server compares the client's requested protocolVersion against the versions it implements (and honors the enableDraft flag for draft specs); on mismatch it returns UNSUPPORTED_PROTOCOL_VERSION.","triggerScenarios":"Client sends an initialize request with a protocolVersion string outside the server's supported set (e.g. a very old or not-yet-released version), or requests a draft protocol version while the server was started without draft specs enabled.","commonSituations":"Using an MCP client SDK pinned to an older spec (e.g. 2024-06-25) against a newer toolbox server; the opposite, a bleeding-edge client against an older server; draft-spec clients hitting a production server without --enable-draft-specs (or equivalent); a proxy/cache stripping or mangling the version header.","solutions":["Upgrade the MCP client SDK to one that negotiates one of the server's supported protocol versions (e.g. 2025-11-25 or 2026-07-28).","If the client requires a draft protocol version, start the toolbox server with draft specs enabled.","Check what version string the client sends on initialize and align it with a server-supported version.","If you control the server, update the toolbox binary so its supported-versions list includes the client's version."],"exampleFix":"// before: client hardcodes an unsupported version\nconst client = new McpClient({ protocolVersion: \"2024-06-25\" });\n// after: use a version supported by the server (or omit to negotiate)\nconst client = new McpClient({ protocolVersion: \"2025-11-25\" });","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"// On UNSUPPORTED_PROTOCOL_VERSION, retry with a lower supported version\nif (err.code === -32000 /* UNSUPPORTED_PROTOCOL_VERSION */) {\n  client.setProtocolVersion(\"2025-11-25\");\n  return client.initialize();\n}","preventionTips":["Use an MCP SDK client that performs automatic version negotiation instead of pinning a version","Match client SDK and toolbox server release versions in CI","Enable draft specs on servers whose clients test pre-release protocol versions"],"tags":["mcp","protocol-version","negotiation","compatibility"],"backgroundTag":"unsupported-protocol-version","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}