googleapis/mcp-toolbox · error · jsonrpc.Error

UNSUPPORTED_PROTOCOL_VERSION

UNSUPPORTED_PROTOCOL_VERSION

Error message

unsupported protocol version

What it means

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.

Source

Thrown at internal/server/mcp/jsonrpc/jsonrpc.go:163

	Id      RequestId      `json:"id,omitempty"`
	Params  *RequestParams `json:"params,omitempty"`
}

// NewError is the standard JSONRPC response sent back when an error has been encountered.
func NewError(id RequestId, code int, message string, data any) JSONRPCError {
	return JSONRPCError{
		Jsonrpc: JSONRPC_VERSION,
		Id:      id,
		Error: Error{
			Code:    code,
			Message: message,
			Data:    data,
		},
	}
}

func NewUnsupportedProtocolVersionError(id RequestId, v string, enableDraft bool) (JSONRPCError, error) {
	err := fmt.Errorf("unsupported protocol version")
	return JSONRPCError{
		Jsonrpc: JSONRPC_VERSION,
		Id:      id,
		Error: Error{
			Code:    UNSUPPORTED_PROTOCOL_VERSION,
			Message: err.Error(),
			Data: struct {
				Supported []string `json:"supported"`
				Requested string   `json:"requested"`
			}{
				Supported: mcputil.GetSupportedVersions(enableDraft),
				Requested: v,
			},
		},
	}, err
}

func NewHeaderMismatchedError(id RequestId, err error) JSONRPCError {

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. 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).
2. If the client requires a draft protocol version, start the toolbox server with draft specs enabled.
3. Check what version string the client sends on initialize and align it with a server-supported version.
4. If you control the server, update the toolbox binary so its supported-versions list includes the client's version.

Example fix

// before: client hardcodes an unsupported version
const client = new McpClient({ protocolVersion: "2024-06-25" });
// after: use a version supported by the server (or omit to negotiate)
const client = new McpClient({ protocolVersion: "2025-11-25" });

// On UNSUPPORTED_PROTOCOL_VERSION, retry with a lower supported version
if (err.code === -32000 /* UNSUPPORTED_PROTOCOL_VERSION */) {
  client.setProtocolVersion("2025-11-25");
  return client.initialize();
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• METHOD_NOT_FOUND
• MCP Auth cannot be enabled together with the legacy HTTP API
• MCP Auth is enabled but Toolbox URL is missing. Please provi
• invalid notification request: %w
• INTERNAL_ERROR

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/059f6ec9432d8c9a. Report an issue: GitHub.